@axhub/genie 0.2.11 → 0.2.12

package/server/acp-runtime/client.js

@@ -13,8 +13,16 @@ import {
 import {
   CONVERSATION_EVENT_KINDS,
   createConversationEvent,
+  createUserMessageConversationEvent,
   stripAssistantProtocolTags
 } from '../../shared/conversationEvents.js';
+import {
+  buildAcpCapabilities,
+  normalizeAcpAvailableCommands,
+  normalizeAcpConfigOptions,
+  normalizeAcpModeState,
+  normalizeAcpTokenUsage
+} from '../../shared/acpCapabilities.js';
 import { parseDataUrl } from '../utils/agentImages.js';
 import { spawnCommand } from '../utils/spawnCommand.js';
 import { resolveCommandPath } from '../utils/resolveCommandPath.js';
@@ -22,10 +30,30 @@ import { resolveAgentCommand } from './registry.js';
 
 const DEFAULT_TERMINAL_OUTPUT_LIMIT = 256 * 1024;
 const DEFAULT_CLOSE_GRACE_MS = 1000;
+const DEFAULT_CANCEL_GRACE_MS = normalizePromptTimeoutMs(process.env.ACP_CANCEL_GRACE_MS, 3000);
 const DEFAULT_TERMINAL_MAX_LIFETIME_MS = parseInt(process.env.ACP_TERMINAL_MAX_LIFETIME_MS, 10) || (5 * 60 * 1000);
+const DEFAULT_START_TIMEOUT_MS = normalizePromptTimeoutMs(
+  process.env.ACP_START_TIMEOUT_MS ?? process.env.AXHUB_GENIE_ACP_START_TIMEOUT_MS,
+  45 * 1000
+);
+const DEFAULT_SESSION_TIMEOUT_MS = normalizePromptTimeoutMs(
+  process.env.ACP_SESSION_TIMEOUT_MS ?? process.env.AXHUB_GENIE_ACP_SESSION_TIMEOUT_MS,
+  45 * 1000
+);
+const DEFAULT_PROMPT_TIMEOUT_MS = normalizePromptTimeoutMs(
+  process.env.ACP_PROMPT_INACTIVITY_TIMEOUT_MS
+    ?? process.env.AXHUB_GENIE_ACP_PROMPT_INACTIVITY_TIMEOUT_MS
+    ?? process.env.ACP_PROMPT_TIMEOUT_MS
+    ?? process.env.AXHUB_GENIE_ACP_PROMPT_TIMEOUT_MS,
+  600 * 1000
+);
+const START_TIMEOUT_ERROR_CODE = 'ACP_START_TIMEOUT';
+const SESSION_TIMEOUT_ERROR_CODE = 'ACP_SESSION_TIMEOUT';
+const PROMPT_TIMEOUT_ERROR_CODE = 'ACP_PROMPT_INACTIVITY_TIMEOUT';
 const FILTERED_CHILD_PROCESS_ENV_KEYS = new Set(['NODE_OPTIONS']);
 
 const pendingPermissionRequests = new Map();
+const pendingElicitationRequests = new Map();
 const loggedMalformedUsageUpdates = new Set();
 
 function getDisabledClaudeAcpMcpServers() {
@@ -42,9 +70,60 @@ function getDisabledClaudeAcpMcpServers() {
 }
 
 function cloneJsonValue(value) {
+  if (value === undefined) {
+    return undefined;
+  }
+
   return JSON.parse(JSON.stringify(value));
 }
 
+function normalizePromptTimeoutMs(value, fallback) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed >= 0
+    ? Math.floor(parsed)
+    : fallback;
+}
+
+function createPromptTimeoutError(agentKey, timeoutMs, details = {}) {
+  const error = new Error(`${agentKey || 'ACP'} ACP prompt inactivity timed out after ${timeoutMs}ms`);
+  error.code = PROMPT_TIMEOUT_ERROR_CODE;
+  error.details = {
+    timeoutMs,
+    ...details
+  };
+  return error;
+}
+
+function createLifecycleTimeoutError(agentKey, operation, timeoutMs, code) {
+  const error = new Error(`${agentKey || 'ACP'} ACP ${operation} timed out after ${timeoutMs}ms`);
+  error.code = code;
+  return error;
+}
+
+function withAcpOperationTimeout(promise, {
+  agentKey = 'ACP',
+  operation = 'operation',
+  timeoutMs = 0,
+  code = START_TIMEOUT_ERROR_CODE
+} = {}) {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    return promise;
+  }
+
+  let timeoutId = null;
+  const timeoutPromise = new Promise((_, reject) => {
+    timeoutId = setTimeout(() => {
+      reject(createLifecycleTimeoutError(agentKey, operation, timeoutMs, code));
+    }, timeoutMs);
+  });
+
+  return Promise.race([promise, timeoutPromise]).finally(() => {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+  });
+}
+
 function logMalformedUsageUpdate(agentKey, sessionId, used, size) {
   const cacheKey = `${agentKey || 'unknown'}:${sessionId || 'unknown'}:${String(used)}:${String(size)}`;
   if (loggedMalformedUsageUpdates.has(cacheKey)) {
@@ -205,6 +284,10 @@ function normalizeText(value) {
   return typeof value === 'string' ? value : String(value ?? '');
 }
 
+function normalizePromptEchoText(value) {
+  return String(value || '').replace(/\r\n/g, '\n').trim();
+}
+
 function normalizeComparableValue(value) {
   try {
     return JSON.stringify(value ?? null);
@@ -389,6 +472,26 @@ function choosePermissionResponse(request, decision = {}) {
   return rejectMatch ? createSelectedPermissionResponse(rejectMatch.optionId) : createCancelledPermissionResponse();
 }
 
+function normalizeElicitationResponse(decision = {}) {
+  const action = String(decision?.action || '').trim().toLowerCase();
+
+  if (action === 'accept') {
+    const content = decision?.content && typeof decision.content === 'object' && !Array.isArray(decision.content)
+      ? cloneJsonValue(decision.content)
+      : {};
+    return {
+      action: 'accept',
+      content
+    };
+  }
+
+  if (action === 'decline') {
+    return { action: 'decline' };
+  }
+
+  return { action: 'cancel' };
+}
+
 function readLines(content, line = null, limit = null) {
   if (line == null && limit == null) {
     return content;
@@ -512,68 +615,9 @@ function buildToolCallConversationPayload(update = {}, toolName = 'Tool') {
   return payload;
 }
 
-function normalizeSessionModeState(modes) {
-  if (!modes || typeof modes !== 'object') {
-    return null;
-  }
-
-  const availableModes = Array.isArray(modes.availableModes)
-    ? modes.availableModes
-        .map((mode) => {
-          if (!mode || typeof mode !== 'object') {
-            return null;
-          }
-
-          const id = String(mode.id || '').trim();
-          if (!id) {
-            return null;
-          }
-
-          return {
-            id,
-            name: String(mode.name || id),
-            description: mode.description == null ? null : String(mode.description)
-          };
-        })
-        .filter(Boolean)
-    : [];
-
-  const currentModeId = String(modes.currentModeId || '').trim();
-
-  if (!currentModeId && availableModes.length === 0) {
-    return null;
-  }
-
-  return {
-    availableModes,
-    currentModeId: currentModeId || null
-  };
-}
-
 function normalizeAvailableCommandsUpdate(update = {}) {
-  const availableCommands = Array.isArray(update.availableCommands)
-    ? update.availableCommands
-        .map((command) => {
-          if (!command || typeof command !== 'object') {
-            return null;
-          }
-
-          const name = String(command.name || '').trim();
-          if (!name) {
-            return null;
-          }
-
-          return {
-            name,
-            description: command.description == null ? '' : String(command.description),
-            input: command.input ? cloneJsonValue(command.input) : null
-          };
-        })
-        .filter(Boolean)
-    : [];
-
   return {
-    availableCommands
+    availableCommands: normalizeAcpAvailableCommands(update)
   };
 }
 
@@ -775,7 +819,7 @@ async function resolveNpxFallbackCommand(commandLine, agentKey) {
 
   const npmCheck = await resolveCommandPath('npm');
   if (npmCheck.found) {
-    return ['npm', 'exec', '--yes', '--', ...parsed.args].join(' ');
+    return convertNpxCommandToNpmExec(commandLine);
   }
 
   throw new Error(
@@ -783,6 +827,142 @@ async function resolveNpxFallbackCommand(commandLine, agentKey) {
   );
 }
 
+async function resolveOpencodeCommand(commandLine) {
+  const parsed = splitCommandLine(commandLine);
+  if (parsed.command !== 'opencode') {
+    return commandLine;
+  }
+
+  const opencodeCheck = await resolveCommandPath('opencode');
+  if (opencodeCheck.found) {
+    return commandLine;
+  }
+
+  return resolveNpxFallbackCommand('npx -y opencode-ai acp', 'opencode');
+}
+
+function buildCommandLineFromAdapterArgs(command, args = []) {
+  const parts = [command, ...args].map((part) => String(part || '').trim()).filter(Boolean);
+  return parts.join(' ');
+}
+
+function convertNpxCommandToNpmExec(commandLine) {
+  const parsed = splitCommandLine(commandLine);
+  if (parsed.command !== 'npx') {
+    return commandLine;
+  }
+
+  const normalizedArgs = [...parsed.args];
+  while (normalizedArgs[0] === '-y' || normalizedArgs[0] === '--yes') {
+    normalizedArgs.shift();
+  }
+
+  return buildCommandLineFromAdapterArgs('npm exec --yes --', normalizedArgs);
+}
+
+function isSpawnEnoentError(error) {
+  return Boolean(error && typeof error === 'object' && error.code === 'ENOENT');
+}
+
+function waitForChildProcessSpawn(childProcess) {
+  return new Promise((resolve, reject) => {
+    const cleanup = () => {
+      childProcess.off?.('spawn', onSpawn);
+      childProcess.off?.('error', onError);
+    };
+
+    const onSpawn = () => {
+      cleanup();
+      resolve(childProcess);
+    };
+
+    const onError = (error) => {
+      cleanup();
+      reject(error);
+    };
+
+    childProcess.once('spawn', onSpawn);
+    childProcess.once('error', onError);
+  });
+}
+
+function waitForChildProcessClose(childProcess, graceMs = DEFAULT_CLOSE_GRACE_MS) {
+  return new Promise((resolve) => {
+    if (!childProcess || childProcess.exitCode != null || childProcess.signalCode != null) {
+      resolve(true);
+      return;
+    }
+
+    let settled = false;
+    const finalize = (value) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      resolve(value);
+    };
+
+    const timer = setTimeout(() => finalize(false), graceMs);
+    childProcess.once?.('close', () => {
+      clearTimeout(timer);
+      finalize(true);
+    });
+  });
+}
+
+function terminateChildProcessTree(childProcess, signal = 'SIGTERM') {
+  if (!childProcess || childProcess.killed) {
+    return false;
+  }
+
+  if (process.platform !== 'win32' && Number.isInteger(childProcess.pid)) {
+    try {
+      process.kill(-childProcess.pid, signal);
+      return true;
+    } catch (error) {
+      if (error?.code !== 'ESRCH' && error?.code !== 'EINVAL') {
+        console.warn(`[ACP] Failed to terminate child process group ${childProcess.pid}: ${error.message}`);
+      }
+    }
+  }
+
+  try {
+    childProcess.kill(signal);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function startAcpChildProcess({ commandLine, projectPath, env, spawnImpl = spawnCommand }) {
+  const spawnAttempt = (attemptCommandLine) => {
+    const { command, args } = splitCommandLine(attemptCommandLine);
+    const childProcess = spawnImpl(command, args, {
+      cwd: projectPath,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
+      detached: process.platform !== 'win32',
+      env
+    });
+    return waitForChildProcessSpawn(childProcess);
+  };
+
+  try {
+    return await spawnAttempt(commandLine);
+  } catch (error) {
+    if (!isSpawnEnoentError(error)) {
+      throw error;
+    }
+
+    const fallbackCommandLine = convertNpxCommandToNpmExec(commandLine);
+    if (fallbackCommandLine === commandLine) {
+      throw error;
+    }
+
+    return spawnAttempt(fallbackCommandLine);
+  }
+}
+
 export async function resolveLaunchCommand(agentKey, overrides = {}) {
   const commandLine = resolveAgentCommand(agentKey, overrides);
   if (!commandLine) {
@@ -796,6 +976,10 @@ export async function resolveLaunchCommand(agentKey, overrides = {}) {
     return resolveGeminiCommand(resolvedCommandLine);
   }
 
+  if (normalizedAgentKey === 'opencode') {
+    return resolveOpencodeCommand(resolvedCommandLine);
+  }
+
   return resolvedCommandLine;
 }
 
@@ -943,7 +1127,14 @@ export class AcpClient {
     projectPath,
     agentCommandOverrides = {},
     model = null,
-    permissionMode = 'default'
+    permissionMode = 'default',
+    modeId = null,
+    thoughtLevel = null,
+    promptTimeoutMs = DEFAULT_PROMPT_TIMEOUT_MS,
+    startTimeoutMs = DEFAULT_START_TIMEOUT_MS,
+    sessionTimeoutMs = DEFAULT_SESSION_TIMEOUT_MS,
+    startChildProcess = startAcpChildProcess,
+    createConnection = (handlers, stream) => new ClientSideConnection(handlers, stream)
   }) {
     this.agentKey = String(agentKey || '').trim().toLowerCase();
     this.writer = writer;
@@ -951,26 +1142,54 @@ export class AcpClient {
     this.agentCommandOverrides = agentCommandOverrides || {};
     this.model = model || null;
     this.permissionMode = permissionMode || 'default';
+    this.modeId = typeof modeId === 'string' && modeId.trim() ? modeId.trim() : null;
+    this.thoughtLevel = typeof thoughtLevel === 'string' && thoughtLevel.trim() ? thoughtLevel.trim() : null;
+    this.promptTimeoutMs = normalizePromptTimeoutMs(promptTimeoutMs, DEFAULT_PROMPT_TIMEOUT_MS);
+    this.startTimeoutMs = normalizePromptTimeoutMs(startTimeoutMs, DEFAULT_START_TIMEOUT_MS);
+    this.sessionTimeoutMs = normalizePromptTimeoutMs(sessionTimeoutMs, DEFAULT_SESSION_TIMEOUT_MS);
+    this.startChildProcess = typeof startChildProcess === 'function' ? startChildProcess : startAcpChildProcess;
+    this.createConnection = typeof createConnection === 'function'
+      ? createConnection
+      : ((handlers, stream) => new ClientSideConnection(handlers, stream));
+    this.configOptionIdsByCategory = new Map();
+    this.configOptionIdsByKey = new Map();
 
     this.childProcess = null;
     this.connection = null;
     this.sessionId = null;
     this.initializeResult = null;
     this.suppressSessionUpdates = false;
+    this.isLoadingSessionReplay = false;
     this.pendingPermissionIds = new Set();
+    this.pendingElicitationIds = new Set();
     this.terminalProcesses = new Map();
     this.spawnCleanup = null;
     this.turnQueue = Promise.resolve();
     this.isPromptInFlight = false;
     this.pendingPromptDiagnostic = null;
+    this.pendingPromptTurnCompletion = null;
+    this.activePromptClientRequestId = null;
+    this.activePromptText = null;
+    this.isReplayingPromptHistory = false;
+    this.hasObservedActivePromptEcho = false;
     this.hasReportedPromptFatalError = false;
     this.agentDiagnosticBuffer = '';
+    this.promptActivity = {
+      timer: null,
+      reject: null,
+      timeoutMs: this.promptTimeoutMs,
+      startedAt: null,
+      lastActivityAt: null,
+      lastActivityKind: null,
+      pauseCount: 0
+    };
     this.streamState = {
       turnId: null,
       assistantSegmentIndex: 0,
       assistantMessageId: null,
       assistantTextStarted: false,
       reasoningMessageId: null,
+      textStreamsClosedForTurn: false,
       toolCalls: new Map()
     };
   }
@@ -997,7 +1216,38 @@ export class AcpClient {
     }
   }
 
-  async configureForTurn({ writer, permissionMode = null, model = null } = {}) {
+  noteConfigOptions(configOptions = []) {
+    const normalizedConfigOptions = normalizeAcpConfigOptions(configOptions);
+    for (const option of normalizedConfigOptions) {
+      const configId = String(option.id || option.key || option.category || '').trim();
+      if (!configId) {
+        continue;
+      }
+
+      if (option.key) {
+        this.configOptionIdsByKey.set(option.key, configId);
+      }
+
+      if (option.category) {
+        this.configOptionIdsByCategory.set(option.category, configId);
+      }
+    }
+
+    return normalizedConfigOptions;
+  }
+
+  resolveConfigOptionId(canonicalKey) {
+    const normalizedKey = String(canonicalKey || '').trim();
+    if (!normalizedKey) {
+      return null;
+    }
+
+    return this.configOptionIdsByCategory.get(normalizedKey) ||
+      this.configOptionIdsByKey.get(normalizedKey) ||
+      normalizedKey;
+  }
+
+  async configureForTurn({ writer, permissionMode = null, model = null, modeId = null, thoughtLevel = null } = {}) {
     if (writer !== undefined) {
       this.attachWriter(writer);
     }
@@ -1013,9 +1263,35 @@ export class AcpClient {
         await this.setModel(model);
       }
     }
+
+    const normalizedModeId = typeof modeId === 'string' && modeId.trim() ? modeId.trim() : null;
+    if (normalizedModeId) {
+      const shouldUpdateMode = normalizedModeId !== this.modeId;
+      this.modeId = normalizedModeId;
+      if (shouldUpdateMode && this.connection && this.sessionId) {
+        await this.setMode(normalizedModeId);
+      }
+    }
+
+    const normalizedThoughtLevel = typeof thoughtLevel === 'string' && thoughtLevel.trim()
+      ? thoughtLevel.trim()
+      : null;
+    if (normalizedThoughtLevel) {
+      const shouldUpdateThoughtLevel = normalizedThoughtLevel !== this.thoughtLevel;
+      this.thoughtLevel = normalizedThoughtLevel;
+      if (shouldUpdateThoughtLevel && this.connection && this.sessionId) {
+        await this.setConfigOption(this.resolveConfigOptionId('thought_level'), normalizedThoughtLevel);
+      }
+    }
   }
 
   emitConversationEvent(kind, payload = {}, options = {}) {
+    const replayExtensions = this.isLoadingSessionReplay
+      ? { runtimeReplay: true }
+      : {};
+    const replaySourceType = this.isLoadingSessionReplay
+      ? 'acp-session-loaded-replay'
+      : null;
     const event = createConversationEvent({
       kind,
       provider: this.agentKey,
@@ -1024,11 +1300,12 @@ export class AcpClient {
       payload,
       extensions: {
         runtimeSource: 'acp',
+        ...replayExtensions,
         ...(options.extensions || {})
       },
       rawRef: {
         runtime: 'acp',
-        sourceType: options.sourceType || 'acp-session-update'
+        sourceType: replaySourceType || options.sourceType || 'acp-session-update'
       }
     });
 
@@ -1060,13 +1337,19 @@ export class AcpClient {
 
     this.hasReportedPromptFatalError = true;
     const errorMessage = error?.message || 'Agent prompt failed.';
+    const errorCode = error?.code || null;
+    const errorDetails = error?.details && typeof error.details === 'object'
+      ? cloneJsonValue(error.details)
+      : null;
 
     const failedAt = nowIso();
     this.flushOpenTextStreams(failedAt);
     this.emitConversationEvent(
       CONVERSATION_EVENT_KINDS.ERROR,
       {
-        message: errorMessage
+        message: errorMessage,
+        ...(errorCode ? { code: errorCode } : {}),
+        ...(errorDetails ? { details: errorDetails } : {})
       },
       {
         timestamp: failedAt,
@@ -1077,7 +1360,9 @@ export class AcpClient {
       CONVERSATION_EVENT_KINDS.SESSION_STATE_CHANGED,
       {
         state: 'errored',
-        message: errorMessage
+        message: errorMessage,
+        ...(errorCode ? { code: errorCode } : {}),
+        ...(errorDetails ? { details: errorDetails } : {})
       },
       {
         timestamp: failedAt,
@@ -1096,6 +1381,8 @@ export class AcpClient {
       return;
     }
 
+    this.notePromptActivity('stderr_diagnostic');
+
     const nextBuffer = this.agentDiagnosticBuffer
       ? `${this.agentDiagnosticBuffer}\n${diagnosticText}`
       : diagnosticText;
@@ -1126,6 +1413,114 @@ export class AcpClient {
     }
   }
 
+  createPromptTimeoutDetails() {
+    const now = Date.now();
+    const startedAt = this.promptActivity.startedAt;
+    const lastActivityAt = this.promptActivity.lastActivityAt;
+    return {
+      timeoutMs: this.promptActivity.timeoutMs,
+      lastActivityAt: lastActivityAt ? new Date(lastActivityAt).toISOString() : null,
+      lastActivityKind: this.promptActivity.lastActivityKind || null,
+      promptAgeMs: startedAt ? Math.max(0, now - startedAt) : null,
+      pendingPermissionCount: this.pendingPermissionIds.size,
+      pendingElicitationCount: this.pendingElicitationIds.size,
+      stderrTail: this.agentDiagnosticBuffer || ''
+    };
+  }
+
+  clearPromptActivityTimer() {
+    if (this.promptActivity.timer) {
+      clearTimeout(this.promptActivity.timer);
+      this.promptActivity.timer = null;
+    }
+  }
+
+  schedulePromptActivityTimer() {
+    this.clearPromptActivityTimer();
+    const timeoutMs = this.promptActivity.timeoutMs;
+    if (
+      !this.isPromptInFlight ||
+      !this.promptActivity.reject ||
+      !Number.isFinite(timeoutMs) ||
+      timeoutMs <= 0 ||
+      this.promptActivity.pauseCount > 0
+    ) {
+      return;
+    }
+
+    this.promptActivity.timer = setTimeout(() => {
+      this.promptActivity.timer = null;
+      const reject = this.promptActivity.reject;
+      if (reject) {
+        reject(createPromptTimeoutError(this.agentKey, timeoutMs, this.createPromptTimeoutDetails()));
+      }
+    }, timeoutMs);
+  }
+
+  startPromptActivityWatchdog(reject, timeoutMs) {
+    const now = Date.now();
+    this.promptActivity = {
+      timer: null,
+      reject,
+      timeoutMs,
+      startedAt: now,
+      lastActivityAt: now,
+      lastActivityKind: 'prompt_sent',
+      pauseCount: 0
+    };
+    this.schedulePromptActivityTimer();
+  }
+
+  stopPromptActivityWatchdog() {
+    this.clearPromptActivityTimer();
+    this.promptActivity.reject = null;
+    this.promptActivity.pauseCount = 0;
+  }
+
+  resolvePromptTurnCompletion(stopReason = 'end_turn') {
+    if (!this.isPromptInFlight || !this.pendingPromptTurnCompletion) {
+      return false;
+    }
+
+    if (this.isLoadingSessionReplay || this.isReplayingPromptHistory) {
+      return false;
+    }
+
+    const resolve = this.pendingPromptTurnCompletion;
+    this.pendingPromptTurnCompletion = null;
+    resolve({ stopReason });
+    return true;
+  }
+
+  notePromptActivity(kind) {
+    if (!this.isPromptInFlight) {
+      return;
+    }
+    this.promptActivity.lastActivityAt = Date.now();
+    this.promptActivity.lastActivityKind = kind || 'activity';
+    this.schedulePromptActivityTimer();
+  }
+
+  pausePromptActivityWatchdog(kind = 'paused') {
+    if (!this.isPromptInFlight) {
+      return;
+    }
+    this.promptActivity.pauseCount += 1;
+    this.promptActivity.lastActivityAt = Date.now();
+    this.promptActivity.lastActivityKind = kind;
+    this.clearPromptActivityTimer();
+  }
+
+  resumePromptActivityWatchdog(kind = 'resumed') {
+    if (!this.isPromptInFlight) {
+      return;
+    }
+    this.promptActivity.pauseCount = Math.max(0, this.promptActivity.pauseCount - 1);
+    this.promptActivity.lastActivityAt = Date.now();
+    this.promptActivity.lastActivityKind = kind;
+    this.schedulePromptActivityTimer();
+  }
+
   async runExclusive(operation) {
     const previousTurn = this.turnQueue.catch(() => {});
     let releaseTurn;
@@ -1160,6 +1555,39 @@ export class AcpClient {
     );
   }
 
+  normalizeAcpMessageId(messageId, prefix = 'assistant_text') {
+    const normalizedMessageId = typeof messageId === 'string' && messageId.trim()
+      ? messageId.trim()
+      : null;
+    if (!normalizedMessageId) {
+      return this.createAssistantMessageId(prefix);
+    }
+
+    const turnId = this.ensureTurnId();
+    return createEventMessageId(
+      prefix,
+      this.agentKey,
+      this.sessionId,
+      `${turnId}:segment-${this.streamState.assistantSegmentIndex}:${normalizedMessageId}`
+    );
+  }
+
+  prepareAssistantMessageBoundary(messageId, timestamp, sourceType) {
+    const nextMessageId = this.normalizeAcpMessageId(messageId);
+    if (
+      this.streamState.assistantMessageId &&
+      this.streamState.assistantMessageId !== nextMessageId
+    ) {
+      this.closeAssistantMessageBoundary(timestamp, sourceType);
+    }
+
+    if (!this.streamState.assistantMessageId) {
+      this.streamState.assistantMessageId = nextMessageId;
+    }
+
+    return this.streamState.assistantMessageId;
+  }
+
   closeAssistantMessageBoundary(timestamp = nowIso(), sourceType = 'acp-message-boundary') {
     const hadAssistantBoundary = Boolean(
       this.streamState.assistantMessageId || this.streamState.assistantTextStarted
@@ -1197,6 +1625,8 @@ export class AcpClient {
       );
       this.streamState.reasoningMessageId = null;
     }
+
+    this.streamState.textStreamsClosedForTurn = true;
   }
 
   resetTurnState({ nextTurnId = randomUUID() } = {}) {
@@ -1204,6 +1634,72 @@ export class AcpClient {
     this.streamState.toolCalls.clear();
     this.streamState.turnId = nextTurnId;
     this.streamState.assistantSegmentIndex = 0;
+    this.streamState.textStreamsClosedForTurn = false;
+    this.isReplayingPromptHistory = false;
+    this.hasObservedActivePromptEcho = false;
+  }
+
+  classifyPromptUserChunk(text) {
+    if (!this.isPromptInFlight) {
+      return {
+        isActivePromptEcho: false,
+        isPromptHistoryReplay: false
+      };
+    }
+
+    const activePromptText = normalizePromptEchoText(this.activePromptText);
+    const chunkText = normalizePromptEchoText(text);
+    const isActivePromptEcho = Boolean(activePromptText && chunkText && activePromptText === chunkText);
+
+    if (isActivePromptEcho) {
+      this.hasObservedActivePromptEcho = true;
+      this.isReplayingPromptHistory = false;
+      return {
+        isActivePromptEcho: true,
+        isPromptHistoryReplay: false
+      };
+    }
+
+    this.isReplayingPromptHistory = true;
+    return {
+      isActivePromptEcho: false,
+      isPromptHistoryReplay: true
+    };
+  }
+
+  buildSessionUpdateEventOptions(sourceType, timestamp) {
+    const replayingPromptHistory = this.isReplayingPromptHistory;
+    const isTextStreamSource = sourceType === 'acp-agent-message' ||
+      sourceType === 'acp-agent-message-boundary' ||
+      sourceType === 'acp-agent-thought';
+    if (this.isLoadingSessionReplay) {
+      return {
+        timestamp,
+        sourceType: 'acp-session-loaded-replay',
+        extensions: { runtimeReplay: true }
+      };
+    }
+
+    if (replayingPromptHistory) {
+      return {
+        timestamp,
+        sourceType: 'acp-prompt-history-replay',
+        extensions: { runtimeReplay: true }
+      };
+    }
+
+    if (isTextStreamSource && this.streamState.textStreamsClosedForTurn) {
+      return {
+        timestamp,
+        sourceType: 'acp-post-turn-replay',
+        extensions: { runtimeReplay: true }
+      };
+    }
+
+    return {
+      timestamp,
+      sourceType
+    };
   }
 
   async handleRequestPermission(request) {
@@ -1235,6 +1731,7 @@ export class AcpClient {
     const timestamp = nowIso();
 
     this.pendingPermissionIds.add(requestId);
+    this.pausePromptActivityWatchdog('approval_request');
 
     this.emitConversationEvent(
       CONVERSATION_EVENT_KINDS.APPROVAL_REQUEST,
@@ -1294,39 +1791,154 @@ export class AcpClient {
       }
     );
 
+    this.resumePromptActivityWatchdog('approval_resolved');
+
     return response;
   }
 
-  async handleSessionUpdate(notification) {
-    if (this.suppressSessionUpdates) {
-      return;
-    }
-
-    const update = notification?.update;
+  async handleCreateElicitation(request) {
+    const requestId = `acp-elicitation:${randomUUID()}`;
     const timestamp = nowIso();
-    if (!update || typeof update !== 'object') {
-      return;
-    }
+    const mode = String(request?.mode || '').trim().toLowerCase() || 'form';
 
-    if (update.sessionUpdate === 'agent_message_chunk') {
+    this.pendingElicitationIds.add(requestId);
+    this.pausePromptActivityWatchdog('elicitation_request');
+
+    this.emitConversationEvent(
+      CONVERSATION_EVENT_KINDS.ELICITATION_REQUEST,
+      {
+        requestId,
+        mode,
+        message: String(request?.message || ''),
+        requestedSchema: request?.requestedSchema && typeof request.requestedSchema === 'object'
+          ? cloneJsonValue(request.requestedSchema)
+          : null,
+        url: typeof request?.url === 'string' ? request.url : null,
+        elicitationId: typeof request?.elicitationId === 'string' ? request.elicitationId : null,
+        scope: {
+          sessionId: request?.sessionId || this.sessionId || null,
+          toolCallId: request?.toolCallId || null,
+          requestId: request?.requestId || null
+        },
+        sessionId: request?.sessionId || this.sessionId || null
+      },
+      {
+        timestamp,
+        extensions: {
+          requestId
+        },
+        sourceType: 'acp-elicitation-request'
+      }
+    );
+
+    const response = await new Promise((resolve) => {
+      pendingElicitationRequests.set(requestId, {
+        request,
+        sessionId: this.sessionId,
+        provider: this.agentKey,
+        resolve
+      });
+    });
+
+    this.pendingElicitationIds.delete(requestId);
+    pendingElicitationRequests.delete(requestId);
+
+    this.emitConversationEvent(
+      CONVERSATION_EVENT_KINDS.ELICITATION_RESOLVED,
+      {
+        requestId,
+        action: response.action,
+        content: response.action === 'accept' ? cloneJsonValue(response.content || {}) : null,
+        message: response.action === 'accept'
+          ? 'User submitted input'
+          : response.action === 'decline'
+            ? 'User declined input'
+            : 'User cancelled input'
+      },
+      {
+        timestamp: nowIso(),
+        extensions: {
+          requestId
+        },
+        sourceType: 'acp-elicitation-resolution'
+      }
+    );
+
+    this.resumePromptActivityWatchdog('elicitation_resolved');
+
+    return response;
+  }
+
+  async handleSessionUpdate(notification) {
+    if (this.suppressSessionUpdates) {
+      return;
+    }
+
+    const update = notification?.update;
+    const timestamp = nowIso();
+    if (!update || typeof update !== 'object') {
+      return;
+    }
+    const updateKind = String(update.sessionUpdate || '').trim() || 'unknown';
+    this.notePromptActivity(`session_update:${updateKind}`);
+
+    if (update.sessionUpdate === 'user_message_chunk') {
       if (update.content?.type === 'text' && typeof update.content.text === 'string') {
-        const cleanText = stripAssistantProtocolTags(update.content.text);
-        if (!cleanText) {
+        const text = update.content.text;
+        if (!text) {
           return;
         }
+        const promptChunk = this.classifyPromptUserChunk(text);
+        const replayExtensions = (
+          this.isLoadingSessionReplay ||
+          promptChunk.isPromptHistoryReplay
+        )
+          ? { runtimeReplay: true }
+          : {};
+        const sourceType = this.isLoadingSessionReplay
+          ? 'acp-session-loaded-replay'
+          : promptChunk.isPromptHistoryReplay
+            ? 'acp-prompt-history-replay'
+            : 'acp-user-message-chunk';
+
+        this.emitPayload({
+          type: 'conversation-event',
+          event: createUserMessageConversationEvent({
+            provider: this.agentKey,
+            sessionId: notification?.sessionId || this.sessionId,
+            timestamp,
+            text,
+            contentBlocks: [],
+            rawRef: {
+              runtime: 'acp',
+              sourceType
+            },
+            clientRequestId: null,
+            extensions: replayExtensions
+          })
+        });
+      }
+      return;
+    }
 
-        const messageId = this.streamState.assistantMessageId
-          || this.createAssistantMessageId('assistant_text');
-
-        if (!this.streamState.assistantMessageId) {
-          this.streamState.assistantMessageId = messageId;
+    if (update.sessionUpdate === 'agent_message_chunk') {
+      if (update.content?.type === 'text' && typeof update.content.text === 'string') {
+        const cleanText = stripAssistantProtocolTags(update.content.text, { trim: false });
+        if (!cleanText) {
+          return;
         }
 
+        const messageId = this.prepareAssistantMessageBoundary(
+          update.messageId,
+          timestamp,
+          'acp-agent-message-boundary'
+        );
+
         if (!this.streamState.assistantTextStarted) {
           this.emitConversationEvent(
             CONVERSATION_EVENT_KINDS.ASSISTANT_TEXT_START,
             { messageId },
-            { timestamp, sourceType: 'acp-agent-message' }
+            this.buildSessionUpdateEventOptions('acp-agent-message', timestamp)
           );
           this.streamState.assistantTextStarted = true;
         }
@@ -1337,22 +1949,18 @@ export class AcpClient {
             messageId,
             text: cleanText
           },
-          {
-            timestamp,
-            sourceType: 'acp-agent-message'
-          }
+          this.buildSessionUpdateEventOptions('acp-agent-message', timestamp)
         );
         return;
       }
 
       const contentBlock = normalizeAssistantContentBlock(update.content);
       if (contentBlock) {
-        const messageId = this.streamState.assistantMessageId
-          || this.createAssistantMessageId('assistant_content');
-
-        if (!this.streamState.assistantMessageId) {
-          this.streamState.assistantMessageId = messageId;
-        }
+        const messageId = this.prepareAssistantMessageBoundary(
+          update.messageId,
+          timestamp,
+          'acp-agent-message-boundary'
+        );
 
         this.emitConversationEvent(
           CONVERSATION_EVENT_KINDS.ASSISTANT_CONTENT_BLOCK,
@@ -1360,10 +1968,7 @@ export class AcpClient {
             messageId,
             contentBlock
           },
-          {
-            timestamp,
-            sourceType: 'acp-agent-message'
-          }
+          this.buildSessionUpdateEventOptions('acp-agent-message', timestamp)
         );
       }
       return;
@@ -1378,7 +1983,7 @@ export class AcpClient {
           this.emitConversationEvent(
             CONVERSATION_EVENT_KINDS.REASONING_START,
             { messageId },
-            { timestamp, sourceType: 'acp-agent-thought' }
+            this.buildSessionUpdateEventOptions('acp-agent-thought', timestamp)
           );
           this.streamState.reasoningMessageId = messageId;
         }
@@ -1389,10 +1994,7 @@ export class AcpClient {
             messageId,
             text: update.content.text
           },
-          {
-            timestamp,
-            sourceType: 'acp-agent-thought'
-          }
+          this.buildSessionUpdateEventOptions('acp-agent-thought', timestamp)
         );
       }
       return;
@@ -1400,6 +2002,7 @@ export class AcpClient {
 
     if (update.sessionUpdate === 'end_turn') {
       this.flushOpenTextStreams(timestamp);
+      this.resolvePromptTurnCompletion('end_turn');
       return;
     }
 
@@ -1447,10 +2050,11 @@ export class AcpClient {
     }
 
     if (update.sessionUpdate === 'config_option_update') {
+      const normalizedConfigOptions = this.noteConfigOptions(update.configOptions || []);
       this.emitConversationEvent(
         CONVERSATION_EVENT_KINDS.CONFIG_OPTION_UPDATE,
         {
-          configOptions: cloneJsonValue(update.configOptions || [])
+          configOptions: cloneJsonValue(normalizedConfigOptions)
         },
         {
           timestamp,
@@ -1557,15 +2161,20 @@ export class AcpClient {
         });
 
         if (resultSignature !== existing.resultSignature) {
+          const resultPayload = {
+            ...toolPayload,
+            content: resultText || '',
+            isError: update.status === 'failed',
+            contentBlocks: Array.isArray(update.content) ? cloneJsonValue(update.content) : []
+          };
+
+          if (update.rawOutput !== undefined) {
+            resultPayload.rawOutput = cloneJsonValue(update.rawOutput);
+          }
+
           this.emitConversationEvent(
             CONVERSATION_EVENT_KINDS.TOOL_RESULT,
-            {
-              ...toolPayload,
-              content: resultText || '',
-              isError: update.status === 'failed',
-              rawOutput: cloneJsonValue(update.rawOutput),
-              contentBlocks: Array.isArray(update.content) ? cloneJsonValue(update.content) : []
-            },
+            resultPayload,
             {
               timestamp,
               sourceType: 'acp-tool-call'
@@ -1588,14 +2197,11 @@ export class AcpClient {
     }
 
     const launchCommand = await resolveLaunchCommand(this.agentKey, this.agentCommandOverrides);
-    const { command, args } = splitCommandLine(launchCommand);
     const spawnEnvironment = await prepareSpawnEnvironment(this.agentKey);
     this.spawnCleanup = spawnEnvironment.cleanup;
-
-    this.childProcess = spawnCommand(command, args, {
-      cwd: this.projectPath,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      windowsHide: true,
+    this.childProcess = await this.startChildProcess({
+      commandLine: launchCommand,
+      projectPath: this.projectPath,
       env: spawnEnvironment.env
     });
 
@@ -1613,10 +2219,12 @@ export class AcpClient {
       this.agentKey
     );
 
-    this.connection = new ClientSideConnection(() => ({
+    this.connection = this.createConnection(() => ({
       requestPermission: (params) => this.handleRequestPermission(params),
+      unstable_createElicitation: (params) => this.handleCreateElicitation(params),
       sessionUpdate: (params) => this.handleSessionUpdate(params),
       readTextFile: async (params) => {
+        this.notePromptActivity('host_tool:readTextFile');
         const resolvedPath = path.isAbsolute(params.path)
           ? params.path
           : path.resolve(this.projectPath, params.path);
@@ -1626,6 +2234,7 @@ export class AcpClient {
         };
       },
       writeTextFile: async (params) => {
+        this.notePromptActivity('host_tool:writeTextFile');
         const resolvedPath = path.isAbsolute(params.path)
           ? params.path
           : path.resolve(this.projectPath, params.path);
@@ -1634,6 +2243,7 @@ export class AcpClient {
         return {};
       },
       createTerminal: async (params) => {
+        this.notePromptActivity('host_tool:createTerminal');
         const terminalId = `terminal:${randomUUID()}`;
         const terminal = new LocalTerminalProcess({
           sessionId: params.sessionId,
@@ -1647,12 +2257,15 @@ export class AcpClient {
         return { terminalId };
       },
       terminalOutput: async (params) => {
+        this.notePromptActivity('host_tool:terminalOutput');
         return this.terminalProcesses.get(params.terminalId)?.currentOutput() || { output: '' };
       },
       waitForTerminalExit: async (params) => {
+        this.notePromptActivity('host_tool:waitForTerminalExit');
         return this.terminalProcesses.get(params.terminalId)?.waitForExit() || {};
       },
       killTerminal: async (params) => {
+        this.notePromptActivity('host_tool:killTerminal');
         const terminal = this.terminalProcesses.get(params.terminalId);
         if (terminal) {
           await terminal.kill();
@@ -1660,6 +2273,7 @@ export class AcpClient {
         return {};
       },
       releaseTerminal: async (params) => {
+        this.notePromptActivity('host_tool:releaseTerminal');
         const terminal = this.terminalProcesses.get(params.terminalId);
         if (terminal) {
           await terminal.release();
@@ -1669,37 +2283,75 @@ export class AcpClient {
       }
     }), stream);
 
-    this.initializeResult = await this.connection.initialize({
-      protocolVersion: PROTOCOL_VERSION,
-      clientCapabilities: {
-        fs: {
-          readTextFile: true,
-          writeTextFile: true
+    try {
+      this.initializeResult = await withAcpOperationTimeout(
+        this.connection.initialize({
+          protocolVersion: PROTOCOL_VERSION,
+          clientCapabilities: {
+            fs: {
+              readTextFile: true,
+              writeTextFile: true
+            },
+            elicitation: {
+              form: {}
+            },
+            terminal: true
+          },
+          clientInfo: {
+            name: '@axhub/genie',
+            title: 'Axhub Genie',
+            version: process.env.APP_VERSION || 'unknown'
+          }
+        }),
+        {
+          agentKey: this.agentKey,
+          operation: 'initialize',
+          timeoutMs: this.startTimeoutMs,
+          code: START_TIMEOUT_ERROR_CODE
         },
-        terminal: true
-      },
-      clientInfo: {
-        name: '@axhub/genie',
-        title: 'Axhub Genie',
-        version: process.env.APP_VERSION || 'unknown'
-      }
-    });
+      );
+    } catch (error) {
+      await this.dispose().catch(() => {});
+      throw error;
+    }
 
     return this.initializeResult;
   }
 
   async createSession() {
-    const response = await this.connection.newSession({
-      cwd: this.projectPath,
-      mcpServers: []
-    });
+    const response = await withAcpOperationTimeout(
+      this.connection.newSession({
+        cwd: this.projectPath,
+        mcpServers: []
+      }),
+      {
+        agentKey: this.agentKey,
+        operation: 'session/new',
+        timeoutMs: this.sessionTimeoutMs,
+        code: SESSION_TIMEOUT_ERROR_CODE
+      }
+    );
 
     this.sessionId = response.sessionId;
     this.attachWriter(this.writer);
-    const normalizedModes = normalizeSessionModeState(response?.modes);
+    const normalizedModes = normalizeAcpModeState(response?.modes);
+    const normalizedConfigOptions = this.noteConfigOptions(response?.configOptions || []);
+    const normalizedTokenUsage = normalizeAcpTokenUsage(response?.tokenUsage || null);
+    const normalizedAvailableCommands = normalizeAcpAvailableCommands(response?.availableCommands || []);
     this.emitPayload({
       type: 'session-created',
-      modes: normalizedModes
+      modes: normalizedModes,
+      configOptions: normalizedConfigOptions,
+      tokenUsage: normalizedTokenUsage,
+      availableCommands: normalizedAvailableCommands,
+      capabilitySnapshot: buildAcpCapabilities({
+        configOptions: normalizedConfigOptions,
+        modeState: normalizedModes,
+        tokenUsage: normalizedTokenUsage,
+        availableCommands: normalizedAvailableCommands,
+        provider: this.agentKey,
+        source: 'session-created'
+      })
     });
 
     if (normalizedModes) {
@@ -1713,10 +2365,176 @@ export class AcpClient {
       );
     }
 
+    if (normalizedConfigOptions.length > 0) {
+      this.emitConversationEvent(
+        CONVERSATION_EVENT_KINDS.CONFIG_OPTION_UPDATE,
+        { configOptions: normalizedConfigOptions },
+        {
+          timestamp: nowIso(),
+          sourceType: 'acp-session-created-config-options'
+        }
+      );
+    }
+
+    if (normalizedAvailableCommands.length > 0) {
+      this.emitConversationEvent(
+        CONVERSATION_EVENT_KINDS.AVAILABLE_COMMANDS_UPDATE,
+        { availableCommands: normalizedAvailableCommands },
+        {
+          timestamp: nowIso(),
+          sourceType: 'acp-session-created-available-commands'
+        }
+      );
+    }
+
+    if (normalizedTokenUsage) {
+      this.emitConversationEvent(
+        CONVERSATION_EVENT_KINDS.USAGE_UPDATE,
+        normalizedTokenUsage,
+        {
+          timestamp: nowIso(),
+          sourceType: 'acp-session-created-usage'
+        }
+      );
+    }
+
+    if (this.model) {
+      await this.setModel(this.model);
+    }
+
+    if (this.modeId) {
+      await this.setMode(this.modeId);
+    }
+
+    if (this.thoughtLevel) {
+      await this.setConfigOption(this.resolveConfigOptionId('thought_level'), this.thoughtLevel);
+    }
+
+    return response;
+  }
+
+  canResumeSession() {
+    const resumeCapability = this.initializeResult?.agentCapabilities?.sessionCapabilities?.resume;
+    return resumeCapability != null && resumeCapability !== false;
+  }
+
+  canListSessions() {
+    const listCapability = this.initializeResult?.agentCapabilities?.sessionCapabilities?.list;
+    return listCapability != null && listCapability !== false;
+  }
+
+  canLoadSession() {
+    return this.initializeResult?.agentCapabilities?.loadSession === true;
+  }
+
+  canCloseSession() {
+    const closeCapability = this.initializeResult?.agentCapabilities?.sessionCapabilities?.close;
+    return closeCapability != null && closeCapability !== false;
+  }
+
+  emitRestoredSessionState(response, sourceLabel) {
+    const normalizedModes = normalizeAcpModeState(response?.modes);
+    const normalizedConfigOptions = this.noteConfigOptions(response?.configOptions || []);
+    const normalizedTokenUsage = normalizeAcpTokenUsage(response?.tokenUsage || null);
+    const normalizedAvailableCommands = normalizeAcpAvailableCommands(response?.availableCommands || []);
+
+    if (normalizedModes) {
+      this.emitConversationEvent(
+        CONVERSATION_EVENT_KINDS.MODE_UPDATE,
+        normalizedModes,
+        {
+          timestamp: nowIso(),
+          sourceType: `acp-session-${sourceLabel}-modes`
+        }
+      );
+    }
+
+    if (normalizedConfigOptions.length > 0) {
+      this.emitConversationEvent(
+        CONVERSATION_EVENT_KINDS.CONFIG_OPTION_UPDATE,
+        { configOptions: normalizedConfigOptions },
+        {
+          timestamp: nowIso(),
+          sourceType: `acp-session-${sourceLabel}-config-options`
+        }
+      );
+    }
+
+    if (normalizedAvailableCommands.length > 0) {
+      this.emitConversationEvent(
+        CONVERSATION_EVENT_KINDS.AVAILABLE_COMMANDS_UPDATE,
+        { availableCommands: normalizedAvailableCommands },
+        {
+          timestamp: nowIso(),
+          sourceType: `acp-session-${sourceLabel}-available-commands`
+        }
+      );
+    }
+
+    if (normalizedTokenUsage) {
+      this.emitConversationEvent(
+        CONVERSATION_EVENT_KINDS.USAGE_UPDATE,
+        normalizedTokenUsage,
+        {
+          timestamp: nowIso(),
+          sourceType: `acp-session-${sourceLabel}-usage`
+        }
+      );
+    }
+  }
+
+  emitLoadedSessionIdleState() {
+    if (this.pendingPermissionIds.size > 0 || this.pendingElicitationIds.size > 0) {
+      return;
+    }
+
+    this.flushOpenTextStreams(nowIso());
+    this.emitConversationEvent(
+      CONVERSATION_EVENT_KINDS.SESSION_STATE_CHANGED,
+      { state: 'idle' },
+      {
+        timestamp: nowIso(),
+        sourceType: 'acp-session-loaded-idle'
+      }
+    );
+  }
+
+  async applyPostSessionRestoreConfiguration() {
     if (this.model) {
       await this.setModel(this.model);
     }
 
+    if (this.modeId) {
+      await this.setMode(this.modeId);
+    }
+
+    if (this.thoughtLevel) {
+      await this.setConfigOption(this.resolveConfigOptionId('thought_level'), this.thoughtLevel);
+    }
+  }
+
+  async resumeSession(sessionId) {
+    this.sessionId = String(sessionId || '').trim();
+    this.attachWriter(this.writer);
+
+    if (typeof this.connection?.resumeSession !== 'function') {
+      throw new Error('ACP connection does not support session/resume');
+    }
+
+    const response = await this.connection.resumeSession({
+      cwd: this.projectPath,
+      mcpServers: [],
+      sessionId: this.sessionId
+    });
+
+    if (typeof response?.sessionId === 'string' && response.sessionId.trim()) {
+      this.sessionId = response.sessionId.trim();
+      this.attachWriter(this.writer);
+    }
+
+    this.emitRestoredSessionState(response, 'resumed');
+    await this.applyPostSessionRestoreConfiguration();
+
     return response;
   }
 
@@ -1724,6 +2542,7 @@ export class AcpClient {
     this.sessionId = String(sessionId || '').trim();
     this.attachWriter(this.writer);
     this.suppressSessionUpdates = Boolean(suppressReplayUpdates);
+    this.isLoadingSessionReplay = true;
     try {
       const response = await this.connection.loadSession({
         cwd: this.projectPath,
@@ -1731,28 +2550,35 @@ export class AcpClient {
         sessionId: this.sessionId
       });
 
-      const normalizedModes = normalizeSessionModeState(response?.modes);
-      if (normalizedModes) {
-        this.emitConversationEvent(
-          CONVERSATION_EVENT_KINDS.MODE_UPDATE,
-          normalizedModes,
-          {
-            timestamp: nowIso(),
-            sourceType: 'acp-session-loaded-modes'
-          }
-        );
-      }
-
-      if (this.model) {
-        await this.setModel(this.model);
-      }
+      this.flushOpenTextStreams(nowIso());
+      this.isLoadingSessionReplay = false;
+      this.emitRestoredSessionState(response, 'loaded');
+      this.emitLoadedSessionIdleState();
+      await this.applyPostSessionRestoreConfiguration();
 
       return response;
     } finally {
       this.suppressSessionUpdates = false;
+      this.isLoadingSessionReplay = false;
     }
   }
 
+  async listSessions({ cursor = null, projectPath = this.projectPath } = {}) {
+    if (typeof this.connection?.listSessions !== 'function') {
+      return { sessions: [], nextCursor: null };
+    }
+
+    const response = await this.connection.listSessions({
+      cwd: projectPath || this.projectPath,
+      cursor
+    });
+
+    return {
+      sessions: Array.isArray(response?.sessions) ? response.sessions : [],
+      nextCursor: response?.nextCursor || null
+    };
+  }
+
   async setModel(modelId) {
     if (!modelId || !this.sessionId || !this.connection) {
       return;
@@ -1794,6 +2620,25 @@ export class AcpClient {
     }
   }
 
+  async setConfigOption(configId, value) {
+    const normalizedConfigId = String(configId || '').trim();
+    if (!normalizedConfigId || value == null || !this.sessionId || !this.connection) {
+      return false;
+    }
+
+    if (typeof this.connection.setSessionConfigOption !== 'function') {
+      return false;
+    }
+
+    await this.connection.setSessionConfigOption({
+      sessionId: this.sessionId,
+      configId: normalizedConfigId,
+      value
+    });
+
+    return true;
+  }
+
   async setMode(modeId) {
     const normalizedModeId = String(modeId || '').trim();
     if (!normalizedModeId || !this.sessionId || !this.connection?.setSessionMode) {
@@ -1807,6 +2652,35 @@ export class AcpClient {
     return true;
   }
 
+  async requestPromptCancellation() {
+    const normalizedSessionId = String(this.sessionId || '').trim();
+    if (!normalizedSessionId || typeof this.connection?.cancel !== 'function') {
+      return false;
+    }
+
+    for (const requestId of this.pendingPermissionIds) {
+      AcpClient.resolvePermissionRequest(requestId, { cancelled: true });
+    }
+
+    for (const requestId of this.pendingElicitationIds) {
+      AcpClient.resolveElicitationRequest(requestId, { action: 'cancel' });
+    }
+
+    let timeoutId = null;
+    try {
+      return await Promise.race([
+        this.connection.cancel({ sessionId: normalizedSessionId }).then(() => true, () => false),
+        new Promise((resolve) => {
+          timeoutId = setTimeout(() => resolve(false), DEFAULT_CLOSE_GRACE_MS);
+        })
+      ]);
+    } finally {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+    }
+  }
+
   async sendPrompt(promptText, attachments = {}) {
     this.resetTurnState();
     this.hasReportedPromptFatalError = false;
@@ -1815,6 +2689,10 @@ export class AcpClient {
     const clientRequestId = typeof attachments?.clientRequestId === 'string' && attachments.clientRequestId.trim()
       ? attachments.clientRequestId.trim()
       : null;
+    this.activePromptClientRequestId = clientRequestId;
+    this.activePromptText = promptPayload.text;
+    this.isReplayingPromptHistory = false;
+    this.hasObservedActivePromptEcho = false;
 
     this.emitConversationEvent(
       CONVERSATION_EVENT_KINDS.USER_MESSAGE,
@@ -1854,6 +2732,28 @@ export class AcpClient {
       };
       this.pendingPromptDiagnostic = diagnosticGuard;
     });
+    let turnCompletionResolve = null;
+    const turnCompletionPromise = new Promise((resolve) => {
+      turnCompletionResolve = resolve;
+      this.pendingPromptTurnCompletion = resolve;
+    });
+    let timeoutGuard = null;
+    const promptTimeoutMs = this.promptTimeoutMs;
+    const timeoutPromise = promptTimeoutMs > 0
+      ? new Promise((_, reject) => {
+          timeoutGuard = {
+            handled: false,
+            reject
+          };
+          this.startPromptActivityWatchdog((error) => {
+            if (timeoutGuard.handled) {
+              return;
+            }
+            timeoutGuard.handled = true;
+            reject(error);
+          }, promptTimeoutMs);
+        })
+      : null;
 
     const promptPromise = this.connection.prompt({
       sessionId: this.sessionId,
@@ -1862,7 +2762,10 @@ export class AcpClient {
     promptPromise.catch(() => {});
 
     try {
-      const response = await Promise.race([promptPromise, diagnosticPromise]);
+      const racedPromises = timeoutPromise
+        ? [promptPromise, diagnosticPromise, turnCompletionPromise, timeoutPromise]
+        : [promptPromise, diagnosticPromise, turnCompletionPromise];
+      const response = await Promise.race(racedPromises);
       const finishedAt = nowIso();
       this.flushOpenTextStreams(finishedAt);
       this.emitConversationEvent(
@@ -1884,17 +2787,28 @@ export class AcpClient {
 
       return response;
     } catch (error) {
+      if (error?.code === PROMPT_TIMEOUT_ERROR_CODE) {
+        await this.requestPromptCancellation();
+      }
       this.reportPromptFailure(error);
       throw error;
     } finally {
+      this.stopPromptActivityWatchdog();
       this.isPromptInFlight = false;
+      this.activePromptClientRequestId = null;
+      this.activePromptText = null;
+      this.isReplayingPromptHistory = false;
+      this.hasObservedActivePromptEcho = false;
       if (this.pendingPromptDiagnostic === diagnosticGuard) {
         this.pendingPromptDiagnostic = null;
       }
+      if (this.pendingPromptTurnCompletion === turnCompletionResolve) {
+        this.pendingPromptTurnCompletion = null;
+      }
     }
   }
 
-  async cancel(sessionId = this.sessionId) {
+  async cancel(sessionId = this.sessionId, { disposeOnTimeout = false, cancelGraceMs = DEFAULT_CANCEL_GRACE_MS } = {}) {
     const normalizedSessionId = String(sessionId || this.sessionId || '').trim();
     if (!normalizedSessionId) {
       return false;
@@ -1904,25 +2818,66 @@ export class AcpClient {
       AcpClient.resolvePermissionRequest(requestId, { cancelled: true });
     }
 
+    for (const requestId of this.pendingElicitationIds) {
+      AcpClient.resolveElicitationRequest(requestId, { action: 'cancel' });
+    }
+
+    let timeoutId = null;
     try {
-      await this.connection.cancel({
-        sessionId: normalizedSessionId
-      });
+      const cancelled = await Promise.race([
+        this.connection.cancel({
+          sessionId: normalizedSessionId
+        }).then(() => true, () => false),
+        new Promise((resolve) => {
+          timeoutId = setTimeout(() => resolve(false), normalizePromptTimeoutMs(cancelGraceMs, DEFAULT_CANCEL_GRACE_MS));
+        })
+      ]);
+      if (!cancelled && disposeOnTimeout) {
+        await this.dispose().catch(() => {});
+      }
       this.emitPayload({
         type: 'session-aborted',
-        success: true
+        success: cancelled
       });
-      return true;
+      return cancelled;
     } catch {
+      if (disposeOnTimeout) {
+        await this.dispose().catch(() => {});
+      }
       return false;
+    } finally {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
     }
   }
 
-  async close() {
+  async closeSession(sessionId = this.sessionId) {
+    const normalizedSessionId = String(sessionId || this.sessionId || '').trim();
+    if (!normalizedSessionId || !this.canCloseSession() || typeof this.connection?.closeSession !== 'function') {
+      return false;
+    }
+
+    try {
+      await this.connection.closeSession({
+        sessionId: normalizedSessionId
+      });
+      return true;
+    } catch (error) {
+      console.warn(`[ACP:${this.agentKey}] Failed to close session ${normalizedSessionId}: ${error.message}`);
+      return false;
+    }
+  }
+
+  async dispose() {
     for (const requestId of this.pendingPermissionIds) {
       AcpClient.resolvePermissionRequest(requestId, { cancelled: true });
     }
 
+    for (const requestId of this.pendingElicitationIds) {
+      AcpClient.resolveElicitationRequest(requestId, { action: 'cancel' });
+    }
+
     for (const [terminalId, terminal] of this.terminalProcesses.entries()) {
       try {
         await terminal.release();
@@ -1935,27 +2890,13 @@ export class AcpClient {
         this.childProcess.stdin.end();
       }
 
-      const closed = await new Promise((resolve) => {
-        let settled = false;
-        const finalize = (value) => {
-          if (settled) {
-            return;
-          }
-          settled = true;
-          resolve(value);
-        };
-
-        const timer = setTimeout(() => finalize(false), DEFAULT_CLOSE_GRACE_MS);
-        this.childProcess.once('close', () => {
-          clearTimeout(timer);
-          finalize(true);
-        });
-      });
-
+      let closed = await waitForChildProcessClose(this.childProcess);
       if (!closed) {
-        try {
-          this.childProcess.kill('SIGTERM');
-        } catch {}
+        terminateChildProcessTree(this.childProcess, 'SIGTERM');
+        closed = await waitForChildProcessClose(this.childProcess);
+      }
+      if (!closed) {
+        terminateChildProcessTree(this.childProcess, 'SIGKILL');
       }
     }
 
@@ -1971,6 +2912,11 @@ export class AcpClient {
     this.initializeResult = null;
   }
 
+  async close() {
+    await this.closeSession().catch(() => false);
+    await this.dispose();
+  }
+
   static resolvePermissionRequest(requestId, decision = {}) {
     const pending = pendingPermissionRequests.get(requestId);
     if (!pending) {
@@ -1980,6 +2926,16 @@ export class AcpClient {
     pending.resolve(choosePermissionResponse(pending.request, decision));
     return true;
   }
+
+  static resolveElicitationRequest(requestId, decision = {}) {
+    const pending = pendingElicitationRequests.get(requestId);
+    if (!pending) {
+      return false;
+    }
+
+    pending.resolve(normalizeElicitationResponse(decision));
+    return true;
+  }
 }
 
 export { normalizeTerminalCommandForSpawn };