@axhub/genie 0.2.6 → 0.2.8

package/server/acp-runtime/client.js

@@ -0,0 +1,1872 @@
+import fs from 'fs/promises';
+import { randomUUID } from 'crypto';
+import os from 'os';
+import path from 'path';
+import { Readable, Writable } from 'stream';
+
+import {
+  ClientSideConnection,
+  PROTOCOL_VERSION,
+  ndJsonStream
+} from '@agentclientprotocol/sdk';
+
+import {
+  CONVERSATION_EVENT_KINDS,
+  createConversationEvent
+} from '../../shared/conversationEvents.js';
+import { parseDataUrl } from '../utils/agentImages.js';
+import { spawnCommand } from '../utils/spawnCommand.js';
+import { resolveCommandPath } from '../utils/resolveCommandPath.js';
+import { resolveAgentCommand } from './registry.js';
+
+const DEFAULT_TERMINAL_OUTPUT_LIMIT = 256 * 1024;
+const DEFAULT_CLOSE_GRACE_MS = 1000;
+const DEFAULT_TERMINAL_MAX_LIFETIME_MS = parseInt(process.env.ACP_TERMINAL_MAX_LIFETIME_MS, 10) || (5 * 60 * 1000);
+const FILTERED_CHILD_PROCESS_ENV_KEYS = new Set(['NODE_OPTIONS']);
+
+const pendingPermissionRequests = new Map();
+
+function getDisabledClaudeAcpMcpServers() {
+  const configured = typeof process.env.CLAUDE_SDK_DISABLED_MCP_SERVERS === 'string'
+    ? process.env.CLAUDE_SDK_DISABLED_MCP_SERVERS
+    : 'pencil';
+
+  return new Set(
+    configured
+      .split(',')
+      .map((value) => value.trim())
+      .filter(Boolean)
+  );
+}
+
+function cloneJsonValue(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function filterClaudeMcpServers(config, disabledServers) {
+  if (!config || typeof config !== 'object' || Array.isArray(config) || disabledServers.size === 0) {
+    return { changed: false, config };
+  }
+
+  const nextConfig = cloneJsonValue(config);
+  let changed = false;
+
+  if (nextConfig.mcpServers && typeof nextConfig.mcpServers === 'object' && !Array.isArray(nextConfig.mcpServers)) {
+    for (const serverName of disabledServers) {
+      if (Object.prototype.hasOwnProperty.call(nextConfig.mcpServers, serverName)) {
+        delete nextConfig.mcpServers[serverName];
+        changed = true;
+      }
+    }
+  }
+
+  if (nextConfig.projects && typeof nextConfig.projects === 'object' && !Array.isArray(nextConfig.projects)) {
+    for (const projectState of Object.values(nextConfig.projects)) {
+      if (!projectState || typeof projectState !== 'object' || Array.isArray(projectState)) {
+        continue;
+      }
+
+      if (projectState.mcpServers && typeof projectState.mcpServers === 'object' && !Array.isArray(projectState.mcpServers)) {
+        for (const serverName of disabledServers) {
+          if (Object.prototype.hasOwnProperty.call(projectState.mcpServers, serverName)) {
+            delete projectState.mcpServers[serverName];
+            changed = true;
+          }
+        }
+      }
+    }
+  }
+
+  return {
+    changed,
+    config: nextConfig
+  };
+}
+
+async function prepareClaudeSpawnEnvironment() {
+  const disabledServers = getDisabledClaudeAcpMcpServers();
+  if (disabledServers.size === 0) {
+    return { env: sanitizeProcessEnv(process.env), cleanup: null };
+  }
+
+  const homeDir = os.homedir();
+  const claudeConfigPath = path.join(homeDir, '.claude.json');
+  let rawConfig;
+
+  try {
+    rawConfig = JSON.parse(await fs.readFile(claudeConfigPath, 'utf8'));
+  } catch {
+    return { env: sanitizeProcessEnv(process.env), cleanup: null };
+  }
+
+  const { changed, config } = filterClaudeMcpServers(rawConfig, disabledServers);
+  if (!changed) {
+    return { env: sanitizeProcessEnv(process.env), cleanup: null };
+  }
+
+  const tempHome = await fs.mkdtemp(path.join(os.tmpdir(), 'axhub-genie-claude-home-'));
+  const sourceClaudeDir = path.join(homeDir, '.claude');
+  const targetClaudeDir = path.join(tempHome, '.claude');
+
+  try {
+    await fs.symlink(sourceClaudeDir, targetClaudeDir, process.platform === 'win32' ? 'junction' : 'dir');
+  } catch {
+    // Claude can still use the temporary config even if the data directory symlink is unavailable.
+  }
+
+  await fs.writeFile(
+    path.join(tempHome, '.claude.json'),
+    `${JSON.stringify(config, null, 2)}\n`,
+    'utf8'
+  );
+
+  return {
+    env: sanitizeProcessEnv(process.env, {
+      HOME: tempHome,
+      USERPROFILE: tempHome
+    }),
+    cleanup: async () => {
+      await fs.rm(tempHome, { recursive: true, force: true });
+    }
+  };
+}
+
+async function prepareSpawnEnvironment(agentKey) {
+  if (String(agentKey || '').trim().toLowerCase() === 'claude') {
+    return prepareClaudeSpawnEnvironment();
+  }
+
+  return { env: sanitizeProcessEnv(process.env), cleanup: null };
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function normalizeText(value) {
+  return typeof value === 'string' ? value : String(value ?? '');
+}
+
+function normalizeComparableValue(value) {
+  try {
+    return JSON.stringify(value ?? null);
+  } catch {
+    return String(value ?? '');
+  }
+}
+
+function sanitizeProcessEnv(baseEnv = process.env, overrides = {}) {
+  const sanitized = {};
+
+  Object.entries(baseEnv || {}).forEach(([key, value]) => {
+    if (!key || value == null || FILTERED_CHILD_PROCESS_ENV_KEYS.has(key)) {
+      return;
+    }
+    sanitized[key] = String(value);
+  });
+
+  Object.entries(overrides || {}).forEach(([key, value]) => {
+    if (!key || value == null) {
+      return;
+    }
+    sanitized[key] = String(value);
+  });
+
+  return sanitized;
+}
+
+function normalizeTerminalCommandForSpawn(command, args = []) {
+  const normalizedArgs = Array.isArray(args) ? [...args] : [];
+  const normalizedCommand = typeof command === 'string' ? command : String(command || '');
+  const commandName = path.basename(normalizedCommand).toLowerCase();
+
+  if (
+    commandName === 'zsh'
+    && normalizedArgs[0] === '-lc'
+    && typeof normalizedArgs[1] === 'string'
+    && !normalizedArgs[1].includes('setopt no_nomatch')
+  ) {
+    normalizedArgs[1] = `setopt no_nomatch; ${normalizedArgs[1]}`;
+  }
+
+  return {
+    command: normalizedCommand,
+    args: normalizedArgs
+  };
+}
+
+function detectFatalAgentDiagnostic(agentKey, text) {
+  const normalizedAgent = String(agentKey || '').trim().toLowerCase();
+  const normalizedText = String(text || '').trim();
+
+  if (!normalizedText) {
+    return null;
+  }
+
+  if (normalizedAgent === 'gemini') {
+    const lowerText = normalizedText.toLowerCase();
+    const isRateLimited = (
+      lowerText.includes('status 429') ||
+      lowerText.includes('ratelimitexceeded') ||
+      lowerText.includes('resource_exhausted') ||
+      lowerText.includes('resource has been exhausted')
+    );
+
+    if (isRateLimited) {
+      return new Error('Gemini request failed because the logged-in account is currently rate limited (429 RESOURCE_EXHAUSTED). Please wait and try again later.');
+    }
+  }
+
+  return null;
+}
+
+function createEventMessageId(prefix, provider, sessionId, turnId = null) {
+  return `${prefix}:${provider}:${sessionId || 'pending'}:${turnId || randomUUID()}`;
+}
+
+function pickPermissionOption(options = [], kinds = []) {
+  for (const kind of kinds) {
+    const match = options.find((option) => option?.kind === kind);
+    if (match) {
+      return match;
+    }
+  }
+  return null;
+}
+
+function createSelectedPermissionResponse(optionId) {
+  return {
+    outcome: {
+      outcome: 'selected',
+      optionId
+    }
+  };
+}
+
+function createCancelledPermissionResponse() {
+  return {
+    outcome: {
+      outcome: 'cancelled'
+    }
+  };
+}
+
+function inferToolKind(toolCall = {}) {
+  if (toolCall.kind) {
+    return toolCall.kind;
+  }
+
+  const title = String(toolCall.title || '').trim().toLowerCase();
+  if (!title) {
+    return 'other';
+  }
+
+  if (title.includes('read') || title.includes('cat')) return 'read';
+  if (title.includes('search') || title.includes('find') || title.includes('grep')) return 'search';
+  if (title.includes('write') || title.includes('edit') || title.includes('patch')) return 'edit';
+  if (title.includes('delete') || title.includes('remove')) return 'delete';
+  if (title.includes('move') || title.includes('rename')) return 'move';
+  if (title.includes('run') || title.includes('bash') || title.includes('shell') || title.includes('exec')) return 'execute';
+  if (title.includes('fetch') || title.includes('http') || title.includes('url')) return 'fetch';
+  if (title.includes('think')) return 'think';
+
+  return 'other';
+}
+
+function classifyPermissionStatus(response, request) {
+  if (!response || response.outcome?.outcome !== 'selected') {
+    return 'cancelled';
+  }
+
+  const selected = request?.options?.find((option) => option.optionId === response.outcome.optionId);
+  if (!selected) {
+    return 'cancelled';
+  }
+
+  if (selected.kind === 'allow_once' || selected.kind === 'allow_always') {
+    return 'approved';
+  }
+
+  return 'denied';
+}
+
+function choosePermissionResponse(request, decision = {}) {
+  const options = Array.isArray(request?.options) ? request.options : [];
+  if (options.length === 0) {
+    return createCancelledPermissionResponse();
+  }
+
+  const explicitOutcome = decision?.outcome;
+  const explicitOptionId = explicitOutcome?.outcome === 'selected'
+    ? explicitOutcome.optionId
+    : decision?.optionId;
+
+  if (explicitOutcome?.outcome === 'cancelled') {
+    return createCancelledPermissionResponse();
+  }
+
+  if (explicitOptionId) {
+    return options.some((option) => option?.optionId === explicitOptionId)
+      ? createSelectedPermissionResponse(explicitOptionId)
+      : createCancelledPermissionResponse();
+  }
+
+  if (decision?.cancelled) {
+    return createCancelledPermissionResponse();
+  }
+
+  if (decision?.allow) {
+    const match = pickPermissionOption(
+      options,
+      decision?.rememberEntry ? ['allow_always', 'allow_once'] : ['allow_once', 'allow_always']
+    );
+    return match ? createSelectedPermissionResponse(match.optionId) : createCancelledPermissionResponse();
+  }
+
+  const rejectMatch = pickPermissionOption(
+    options,
+    decision?.rememberEntry ? ['reject_always', 'reject_once'] : ['reject_once', 'reject_always']
+  );
+
+  return rejectMatch ? createSelectedPermissionResponse(rejectMatch.optionId) : createCancelledPermissionResponse();
+}
+
+function readLines(content, line = null, limit = null) {
+  if (line == null && limit == null) {
+    return content;
+  }
+
+  const lines = String(content || '').split(/\r?\n/);
+  const startIndex = Math.max(0, Number(line || 1) - 1);
+  const endIndex = limit == null ? lines.length : startIndex + Math.max(0, Number(limit) || 0);
+  return lines.slice(startIndex, endIndex).join('\n');
+}
+
+function toContentBlockText(content) {
+  if (!content || typeof content !== 'object') {
+    return '';
+  }
+
+  if (content.type === 'text') {
+    return String(content.text || '');
+  }
+
+  if (content.type === 'image') {
+    return `[image:${content.mimeType || 'unknown'}]`;
+  }
+
+  if (content.type === 'resource_link') {
+    return String(content.uri || content.name || '');
+  }
+
+  if (content.type === 'resource') {
+    const resource = content.resource || {};
+    if (typeof resource.text === 'string') {
+      return resource.text;
+    }
+  }
+
+  if (content.type === 'audio') {
+    return `[audio:${content.mimeType || 'unknown'}]`;
+  }
+
+  try {
+    return JSON.stringify(content);
+  } catch {
+    return String(content);
+  }
+}
+
+function toToolContentText(toolCall = {}) {
+  if (toolCall.rawOutput != null) {
+    return typeof toolCall.rawOutput === 'string'
+      ? toolCall.rawOutput
+      : normalizeComparableValue(toolCall.rawOutput);
+  }
+
+  if (!Array.isArray(toolCall.content) || toolCall.content.length === 0) {
+    return '';
+  }
+
+  return toolCall.content
+    .map((item) => {
+      if (!item || typeof item !== 'object') {
+        return '';
+      }
+
+      if (item.type === 'content') {
+        return toContentBlockText(item.content);
+      }
+
+      if (item.type === 'diff') {
+        return `Diff ${item.path || ''}\n${item.newText || ''}`.trim();
+      }
+
+      if (item.type === 'terminal') {
+        return `Terminal ${item.terminalId || ''}`.trim();
+      }
+
+      return normalizeComparableValue(item);
+    })
+    .filter(Boolean)
+    .join('\n\n');
+}
+
+function createPermissionMessage(toolCall = {}) {
+  const title = String(toolCall.title || 'tool execution').trim();
+  return `Approval required for ${title}`;
+}
+
+function buildToolCallConversationPayload(update = {}, toolName = 'Tool') {
+  const payload = {
+    toolCallId: update.toolCallId,
+    toolName
+  };
+
+  if (update.title != null) {
+    payload.title = String(update.title);
+  }
+
+  if (update.kind != null) {
+    payload.kind = String(update.kind);
+  }
+
+  if (update.status != null) {
+    payload.status = String(update.status);
+  }
+
+  if (update.rawInput !== undefined) {
+    payload.rawInput = cloneJsonValue(update.rawInput);
+  }
+
+  if (update.rawOutput !== undefined) {
+    payload.rawOutput = cloneJsonValue(update.rawOutput);
+  }
+
+  if (Array.isArray(update.content)) {
+    payload.contentBlocks = cloneJsonValue(update.content);
+  }
+
+  if (Array.isArray(update.locations)) {
+    payload.locations = cloneJsonValue(update.locations);
+  }
+
+  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
+  };
+}
+
+function normalizePromptResourceLinks(resourceLinks = []) {
+  return Array.isArray(resourceLinks)
+    ? resourceLinks
+        .map((entry) => {
+          if (typeof entry === 'string') {
+            const uri = entry.trim();
+            if (!uri) return null;
+            return {
+              type: 'resource_link',
+              uri,
+              name: path.basename(uri) || uri
+            };
+          }
+
+          if (!entry || typeof entry !== 'object') {
+            return null;
+          }
+
+          const uri = String(entry.uri || entry.path || entry.url || '').trim();
+          if (!uri) {
+            return null;
+          }
+
+          return {
+            type: 'resource_link',
+            uri,
+            name: entry.name == null ? (path.basename(uri) || uri) : String(entry.name)
+          };
+        })
+        .filter(Boolean)
+    : [];
+}
+
+function buildConversationContentBlocks(images = [], resourceLinks = []) {
+  const blocks = [];
+
+  for (const image of images || []) {
+    if (!image?.data) {
+      continue;
+    }
+
+    blocks.push({
+      type: 'image',
+      data: image.data,
+      mimeType: image.mimeType || 'application/octet-stream',
+      name: image.name || null
+    });
+  }
+
+  blocks.push(...normalizePromptResourceLinks(resourceLinks));
+  return blocks;
+}
+
+function normalizeAssistantContentBlock(content = {}) {
+  if (!content || typeof content !== 'object' || !content.type) {
+    return null;
+  }
+
+  if (content.type === 'text') {
+    return null;
+  }
+
+  if (content.type === 'resource' && content.resource && typeof content.resource === 'object') {
+    return {
+      type: 'resource',
+      resource: cloneJsonValue(content.resource)
+    };
+  }
+
+  return cloneJsonValue(content);
+}
+
+export function splitCommandLine(value) {
+  const source = String(value || '').trim();
+  if (!source) {
+    throw new Error('ACP agent command cannot be empty');
+  }
+
+  const parts = [];
+  let current = '';
+  let quote = null;
+  let escaping = false;
+
+  for (const character of source) {
+    if (escaping) {
+      current += character;
+      escaping = false;
+      continue;
+    }
+
+    if (character === '\\' && quote !== '\'') {
+      escaping = true;
+      continue;
+    }
+
+    if (quote) {
+      if (character === quote) {
+        quote = null;
+      } else {
+        current += character;
+      }
+      continue;
+    }
+
+    if (character === '\'' || character === '"') {
+      quote = character;
+      continue;
+    }
+
+    if (/\s/.test(character)) {
+      if (current) {
+        parts.push(current);
+        current = '';
+      }
+      continue;
+    }
+
+    current += character;
+  }
+
+  if (current) {
+    parts.push(current);
+  }
+
+  if (parts.length === 0) {
+    throw new Error('ACP agent command cannot be empty');
+  }
+
+  return {
+    command: parts[0],
+    args: parts.slice(1)
+  };
+}
+
+function compareVersionParts(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    const leftValue = Number(left[index] || 0);
+    const rightValue = Number(right[index] || 0);
+    if (leftValue > rightValue) return 1;
+    if (leftValue < rightValue) return -1;
+  }
+  return 0;
+}
+
+async function resolveGeminiCommand(commandLine) {
+  const parsed = splitCommandLine(commandLine);
+
+  if (parsed.command !== 'gemini') {
+    return commandLine;
+  }
+
+  try {
+    const versionOutput = await new Promise((resolve, reject) => {
+      let stdout = '';
+      const childProcess = spawnCommand(parsed.command, ['--version'], {
+        stdio: ['ignore', 'pipe', 'ignore']
+      });
+
+      childProcess.stdout.on('data', (chunk) => {
+        stdout += chunk.toString();
+      });
+
+      childProcess.on('close', () => resolve(stdout.trim()));
+      childProcess.on('error', reject);
+    });
+
+    const match = String(versionOutput || '').match(/(\d+)\.(\d+)\.(\d+)/);
+    if (!match) {
+      return commandLine;
+    }
+
+    const versionParts = [Number(match[1]), Number(match[2]), Number(match[3])];
+    if (compareVersionParts(versionParts, [0, 33, 0]) >= 0) {
+      return commandLine;
+    }
+
+    const nextArgs = parsed.args.map((argument) => (
+      argument === '--acp' ? '--experimental-acp' : argument
+    ));
+    return [parsed.command, ...nextArgs].join(' ');
+  } catch {
+    return commandLine;
+  }
+}
+
+async function resolveNpxFallbackCommand(commandLine, agentKey) {
+  const parsed = splitCommandLine(commandLine);
+  if (parsed.command !== 'npx') {
+    return commandLine;
+  }
+
+  const npxCheck = await resolveCommandPath('npx');
+  if (npxCheck.found) {
+    return commandLine;
+  }
+
+  const npmCheck = await resolveCommandPath('npm');
+  if (npmCheck.found) {
+    return ['npm', 'exec', '--yes', '--', ...parsed.args].join(' ');
+  }
+
+  throw new Error(
+    `Unable to launch ${agentKey} ACP adapter because neither npx nor npm is available in PATH.`
+  );
+}
+
+export async function resolveLaunchCommand(agentKey, overrides = {}) {
+  const commandLine = resolveAgentCommand(agentKey, overrides);
+  if (!commandLine) {
+    throw new Error(`Unsupported ACP agent: ${agentKey}`);
+  }
+
+  const normalizedAgentKey = String(agentKey || '').trim().toLowerCase();
+  const resolvedCommandLine = await resolveNpxFallbackCommand(commandLine, normalizedAgentKey || 'unknown');
+
+  if (normalizedAgentKey === 'gemini') {
+    return resolveGeminiCommand(resolvedCommandLine);
+  }
+
+  return resolvedCommandLine;
+}
+
+function buildPromptBlocks(promptText, attachments = {}) {
+  const normalizedAttachments = Array.isArray(attachments)
+    ? { images: attachments }
+    : (attachments && typeof attachments === 'object' ? attachments : {});
+  const blocks = [];
+  const normalizedPromptText = String(promptText || '').trim() || 'Continue.';
+  blocks.push({
+    type: 'text',
+    text: normalizedPromptText
+  });
+
+  for (const image of normalizedAttachments.images || []) {
+    const parsed = parseDataUrl(image?.data);
+    if (!parsed) {
+      continue;
+    }
+
+    blocks.push({
+      type: 'image',
+      data: parsed.base64Data,
+      mimeType: parsed.mimeType
+    });
+  }
+
+  for (const resourceLink of normalizePromptResourceLinks(normalizedAttachments.resourceLinks || [])) {
+    blocks.push(resourceLink);
+  }
+
+  return {
+    blocks,
+    text: normalizedPromptText,
+    contentBlocks: buildConversationContentBlocks(
+      normalizedAttachments.images || [],
+      normalizedAttachments.resourceLinks || []
+    )
+  };
+}
+
+class LocalTerminalProcess {
+  constructor({
+    sessionId,
+    command,
+    args = [],
+    cwd = null,
+    env = [],
+    outputByteLimit = DEFAULT_TERMINAL_OUTPUT_LIMIT,
+    maxLifetimeMs = DEFAULT_TERMINAL_MAX_LIFETIME_MS
+  }) {
+    const normalizedSpawn = normalizeTerminalCommandForSpawn(command, args);
+
+    this.sessionId = sessionId;
+    this.command = normalizedSpawn.command;
+    this.args = normalizedSpawn.args;
+    this.cwd = cwd || process.cwd();
+    this.outputByteLimit = Number(outputByteLimit) > 0 ? Number(outputByteLimit) : DEFAULT_TERMINAL_OUTPUT_LIMIT;
+    this.maxLifetimeMs = Number(maxLifetimeMs) > 0 ? Number(maxLifetimeMs) : DEFAULT_TERMINAL_MAX_LIFETIME_MS;
+    this.output = '';
+    this.exitStatus = null;
+    this.waiters = [];
+    this.maxLifetimeTimer = null;
+
+    const envEntries = Array.isArray(env)
+      ? env.reduce((accumulator, entry) => {
+          if (entry?.name) {
+            accumulator[entry.name] = String(entry.value ?? '');
+          }
+          return accumulator;
+        }, {})
+      : {};
+
+    this.child = spawnCommand(this.command, this.args, {
+      cwd: this.cwd,
+      env: sanitizeProcessEnv(process.env, envEntries),
+      stdio: ['ignore', 'pipe', 'pipe']
+    });
+
+    this.maxLifetimeTimer = setTimeout(() => {
+      void this.kill();
+    }, this.maxLifetimeMs);
+    this.maxLifetimeTimer.unref?.();
+
+    const appendOutput = (chunk) => {
+      this.output += chunk.toString();
+      if (Buffer.byteLength(this.output, 'utf8') > this.outputByteLimit) {
+        const sliced = Buffer.from(this.output, 'utf8').subarray(-this.outputByteLimit);
+        this.output = sliced.toString('utf8');
+      }
+    };
+
+    this.child.stdout.on('data', appendOutput);
+    this.child.stderr.on('data', appendOutput);
+    this.child.on('close', (exitCode, signal) => {
+      if (this.maxLifetimeTimer) {
+        clearTimeout(this.maxLifetimeTimer);
+        this.maxLifetimeTimer = null;
+      }
+      this.exitStatus = {
+        exitCode,
+        signal
+      };
+      this.waiters.splice(0).forEach((resolve) => resolve(this.exitStatus));
+    });
+  }
+
+  currentOutput() {
+    return {
+      output: this.output,
+      exitStatus: this.exitStatus || undefined
+    };
+  }
+
+  async waitForExit() {
+    if (this.exitStatus) {
+      return this.exitStatus;
+    }
+
+    return new Promise((resolve) => {
+      this.waiters.push(resolve);
+    });
+  }
+
+  async kill() {
+    if (!this.exitStatus) {
+      try {
+        this.child.kill('SIGTERM');
+      } catch {}
+    }
+
+    return {};
+  }
+
+  async release() {
+    await this.kill();
+    return {};
+  }
+}
+
+export class AcpClient {
+  constructor({
+    agentKey,
+    writer,
+    projectPath,
+    agentCommandOverrides = {},
+    model = null,
+    permissionMode = 'default'
+  }) {
+    this.agentKey = String(agentKey || '').trim().toLowerCase();
+    this.writer = writer;
+    this.projectPath = path.resolve(projectPath || process.cwd());
+    this.agentCommandOverrides = agentCommandOverrides || {};
+    this.model = model || null;
+    this.permissionMode = permissionMode || 'default';
+
+    this.childProcess = null;
+    this.connection = null;
+    this.sessionId = null;
+    this.initializeResult = null;
+    this.suppressSessionUpdates = false;
+    this.pendingPermissionIds = new Set();
+    this.terminalProcesses = new Map();
+    this.spawnCleanup = null;
+    this.turnQueue = Promise.resolve();
+    this.isPromptInFlight = false;
+    this.pendingPromptDiagnostic = null;
+    this.hasReportedPromptFatalError = false;
+    this.agentDiagnosticBuffer = '';
+    this.streamState = {
+      turnId: null,
+      assistantSegmentIndex: 0,
+      assistantMessageId: null,
+      assistantTextStarted: false,
+      reasoningMessageId: null,
+      toolCalls: new Map()
+    };
+  }
+
+  emitPayload(payload) {
+    if (!this.writer || typeof this.writer.send !== 'function') {
+      return;
+    }
+
+    this.writer.send({
+      provider: this.agentKey,
+      sessionId: this.sessionId,
+      runtime: 'acp',
+      timestamp: nowIso(),
+      ...payload
+    });
+  }
+
+  attachWriter(writer) {
+    this.writer = writer || null;
+    if (this.sessionId) {
+      this.writer?.setSessionId?.(this.sessionId);
+    }
+  }
+
+  async configureForTurn({ writer, permissionMode = null, model = null } = {}) {
+    if (writer !== undefined) {
+      this.attachWriter(writer);
+    }
+
+    if (permissionMode) {
+      this.permissionMode = permissionMode;
+    }
+
+    if (model) {
+      const shouldUpdateModel = model !== this.model;
+      this.model = model;
+      if (shouldUpdateModel && this.connection && this.sessionId) {
+        await this.setModel(model);
+      }
+    }
+  }
+
+  emitConversationEvent(kind, payload = {}, options = {}) {
+    const event = createConversationEvent({
+      kind,
+      provider: this.agentKey,
+      sessionId: this.sessionId,
+      timestamp: options.timestamp || nowIso(),
+      payload,
+      extensions: {
+        runtimeSource: 'acp',
+        ...(options.extensions || {})
+      },
+      rawRef: {
+        runtime: 'acp',
+        sourceType: options.sourceType || 'acp-session-update'
+      }
+    });
+
+    this.emitPayload({
+      type: 'conversation-event',
+      event
+    });
+  }
+
+  emitSystemNotice(message, options = {}) {
+    if (!message) {
+      return;
+    }
+
+    this.emitConversationEvent(
+      CONVERSATION_EVENT_KINDS.SYSTEM_NOTICE,
+      { message },
+      {
+        sourceType: 'acp-system-notice',
+        ...options
+      }
+    );
+  }
+
+  reportPromptFailure(error, { emitRawError = false } = {}) {
+    if (this.hasReportedPromptFatalError) {
+      return;
+    }
+
+    this.hasReportedPromptFatalError = true;
+
+    const failedAt = nowIso();
+    this.flushOpenTextStreams(failedAt);
+    this.emitConversationEvent(
+      CONVERSATION_EVENT_KINDS.SESSION_STATE_CHANGED,
+      {
+        state: 'errored'
+      },
+      {
+        timestamp: failedAt,
+        sourceType: 'acp-prompt-error'
+      }
+    );
+    this.emitPayload({
+      type: 'session-status',
+      isProcessing: false
+    });
+
+    if (emitRawError) {
+      this.emitPayload({
+        type: 'error',
+        error: error?.message || 'Agent prompt failed.'
+      });
+    }
+  }
+
+  handleAgentDiagnostic(text) {
+    const diagnosticText = String(text || '').trim();
+    if (!diagnosticText) {
+      return;
+    }
+
+    const nextBuffer = this.agentDiagnosticBuffer
+      ? `${this.agentDiagnosticBuffer}\n${diagnosticText}`
+      : diagnosticText;
+    this.agentDiagnosticBuffer = nextBuffer.length > 8192
+      ? nextBuffer.slice(-8192)
+      : nextBuffer;
+
+    const fatalError = detectFatalAgentDiagnostic(this.agentKey, this.agentDiagnosticBuffer);
+    if (!fatalError || !this.isPromptInFlight) {
+      return;
+    }
+
+    const pendingDiagnostic = this.pendingPromptDiagnostic;
+    if (pendingDiagnostic?.handled) {
+      return;
+    }
+
+    if (pendingDiagnostic) {
+      pendingDiagnostic.handled = true;
+      this.reportPromptFailure(fatalError, {
+        emitRawError: true
+      });
+      pendingDiagnostic.reject(fatalError);
+    }
+
+    if (this.childProcess && !this.childProcess.killed) {
+      try {
+        this.childProcess.kill('SIGTERM');
+      } catch {}
+    }
+  }
+
+  async runExclusive(operation) {
+    const previousTurn = this.turnQueue.catch(() => {});
+    let releaseTurn;
+
+    this.turnQueue = new Promise((resolve) => {
+      releaseTurn = resolve;
+    });
+
+    await previousTurn;
+
+    try {
+      return await operation();
+    } finally {
+      releaseTurn?.();
+    }
+  }
+
+  ensureTurnId() {
+    if (!this.streamState.turnId) {
+      this.streamState.turnId = randomUUID();
+    }
+    return this.streamState.turnId;
+  }
+
+  createAssistantMessageId(prefix = 'assistant_text') {
+    const turnId = this.ensureTurnId();
+    return createEventMessageId(
+      prefix,
+      this.agentKey,
+      this.sessionId,
+      `${turnId}:segment-${this.streamState.assistantSegmentIndex}`
+    );
+  }
+
+  closeAssistantMessageBoundary(timestamp = nowIso(), sourceType = 'acp-message-boundary') {
+    const hadAssistantBoundary = Boolean(
+      this.streamState.assistantMessageId || this.streamState.assistantTextStarted
+    );
+
+    if (this.streamState.assistantMessageId && this.streamState.assistantTextStarted) {
+      this.emitConversationEvent(
+        CONVERSATION_EVENT_KINDS.ASSISTANT_TEXT_END,
+        { messageId: this.streamState.assistantMessageId },
+        {
+          timestamp,
+          sourceType
+        }
+      );
+    }
+
+    this.streamState.assistantMessageId = null;
+    this.streamState.assistantTextStarted = false;
+    if (hadAssistantBoundary) {
+      this.streamState.assistantSegmentIndex += 1;
+    }
+  }
+
+  flushOpenTextStreams(timestamp = nowIso()) {
+    this.closeAssistantMessageBoundary(timestamp, 'acp-turn-complete');
+
+    if (this.streamState.reasoningMessageId) {
+      this.emitConversationEvent(
+        CONVERSATION_EVENT_KINDS.REASONING_END,
+        { messageId: this.streamState.reasoningMessageId },
+        {
+          timestamp,
+          sourceType: 'acp-turn-complete'
+        }
+      );
+      this.streamState.reasoningMessageId = null;
+    }
+  }
+
+  resetTurnState({ nextTurnId = randomUUID() } = {}) {
+    this.flushOpenTextStreams(nowIso());
+    this.streamState.toolCalls.clear();
+    this.streamState.turnId = nextTurnId;
+    this.streamState.assistantSegmentIndex = 0;
+  }
+
+  async handleRequestPermission(request) {
+    const toolKind = inferToolKind(request?.toolCall);
+    const allowAllOption = pickPermissionOption(request?.options, ['allow_once', 'allow_always']);
+    const rejectOption = pickPermissionOption(request?.options, ['reject_once', 'reject_always']);
+
+    if (this.permissionMode === 'bypassPermissions' && allowAllOption) {
+      return createSelectedPermissionResponse(allowAllOption.optionId);
+    }
+
+    if (this.permissionMode === 'acceptEdits' && ['read', 'search', 'edit', 'move', 'think', 'switch_mode'].includes(toolKind)) {
+      return allowAllOption
+        ? createSelectedPermissionResponse(allowAllOption.optionId)
+        : createCancelledPermissionResponse();
+    }
+
+    if (this.permissionMode === 'plan') {
+      if (['read', 'search', 'fetch', 'think', 'switch_mode'].includes(toolKind) && allowAllOption) {
+        return createSelectedPermissionResponse(allowAllOption.optionId);
+      }
+      if (rejectOption) {
+        return createSelectedPermissionResponse(rejectOption.optionId);
+      }
+      return createCancelledPermissionResponse();
+    }
+
+    const requestId = `acp-permission:${randomUUID()}`;
+    const timestamp = nowIso();
+
+    this.pendingPermissionIds.add(requestId);
+
+    this.emitConversationEvent(
+      CONVERSATION_EVENT_KINDS.APPROVAL_REQUEST,
+      {
+        requestId,
+        toolName: request?.toolCall?.title || 'tool execution',
+        input: request?.toolCall?.rawInput ?? null,
+        options: cloneJsonValue(request?.options || []),
+        toolCall: cloneJsonValue(request?.toolCall || null),
+        context: {
+          kind: toolKind,
+          options: request?.options || []
+        },
+        sessionId: this.sessionId,
+        message: createPermissionMessage(request?.toolCall)
+      },
+      {
+        timestamp,
+        extensions: {
+          requestId
+        },
+        sourceType: 'acp-permission-request'
+      }
+    );
+
+    const response = await new Promise((resolve) => {
+      pendingPermissionRequests.set(requestId, {
+        request,
+        sessionId: this.sessionId,
+        provider: this.agentKey,
+        resolve
+      });
+    });
+
+    this.pendingPermissionIds.delete(requestId);
+    pendingPermissionRequests.delete(requestId);
+
+    const status = classifyPermissionStatus(response, request);
+    this.emitConversationEvent(
+      CONVERSATION_EVENT_KINDS.APPROVAL_RESOLVED,
+      {
+        requestId,
+        status,
+        toolName: request?.toolCall?.title || null,
+        message: status === 'approved'
+          ? `Approved ${request?.toolCall?.title || 'tool execution'}`
+          : status === 'denied'
+            ? `Denied ${request?.toolCall?.title || 'tool execution'}`
+            : `Cancelled ${request?.toolCall?.title || 'tool execution'}`
+      },
+      {
+        timestamp: nowIso(),
+        extensions: {
+          requestId
+        },
+        sourceType: 'acp-permission-resolution'
+      }
+    );
+
+    return response;
+  }
+
+  async handleSessionUpdate(notification) {
+    if (this.suppressSessionUpdates) {
+      return;
+    }
+
+    const update = notification?.update;
+    const timestamp = nowIso();
+    if (!update || typeof update !== 'object') {
+      return;
+    }
+
+    if (update.sessionUpdate === 'agent_message_chunk') {
+      if (update.content?.type === 'text' && typeof update.content.text === 'string') {
+        const messageId = this.streamState.assistantMessageId
+          || this.createAssistantMessageId('assistant_text');
+
+        if (!this.streamState.assistantMessageId) {
+          this.streamState.assistantMessageId = messageId;
+        }
+
+        if (!this.streamState.assistantTextStarted) {
+          this.emitConversationEvent(
+            CONVERSATION_EVENT_KINDS.ASSISTANT_TEXT_START,
+            { messageId },
+            { timestamp, sourceType: 'acp-agent-message' }
+          );
+          this.streamState.assistantTextStarted = true;
+        }
+
+        this.emitConversationEvent(
+          CONVERSATION_EVENT_KINDS.ASSISTANT_TEXT_DELTA,
+          {
+            messageId,
+            text: update.content.text
+          },
+          {
+            timestamp,
+            sourceType: 'acp-agent-message'
+          }
+        );
+        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;
+        }
+
+        this.emitConversationEvent(
+          CONVERSATION_EVENT_KINDS.ASSISTANT_CONTENT_BLOCK,
+          {
+            messageId,
+            contentBlock
+          },
+          {
+            timestamp,
+            sourceType: 'acp-agent-message'
+          }
+        );
+      }
+      return;
+    }
+
+    if (update.sessionUpdate === 'agent_thought_chunk') {
+      if (update.content?.type === 'text' && typeof update.content.text === 'string') {
+        const messageId = this.streamState.reasoningMessageId
+          || createEventMessageId('reasoning', this.agentKey, this.sessionId, this.ensureTurnId());
+
+        if (!this.streamState.reasoningMessageId) {
+          this.emitConversationEvent(
+            CONVERSATION_EVENT_KINDS.REASONING_START,
+            { messageId },
+            { timestamp, sourceType: 'acp-agent-thought' }
+          );
+          this.streamState.reasoningMessageId = messageId;
+        }
+
+        this.emitConversationEvent(
+          CONVERSATION_EVENT_KINDS.REASONING_DELTA,
+          {
+            messageId,
+            text: update.content.text
+          },
+          {
+            timestamp,
+            sourceType: 'acp-agent-thought'
+          }
+        );
+      }
+      return;
+    }
+
+    if (update.sessionUpdate === 'end_turn') {
+      this.flushOpenTextStreams(timestamp);
+      return;
+    }
+
+    if (update.sessionUpdate === 'plan') {
+      this.emitConversationEvent(
+        CONVERSATION_EVENT_KINDS.PLAN_UPDATE,
+        {
+          entries: cloneJsonValue(update.entries || []),
+          message: update.message || 'Implementation plan updated'
+        },
+        {
+          timestamp,
+          sourceType: 'acp-plan'
+        }
+      );
+      return;
+    }
+
+    if (update.sessionUpdate === 'current_mode_update') {
+      const payload = {
+        currentModeId: String(update.currentModeId || '').trim() || null
+      };
+
+      this.emitConversationEvent(
+        CONVERSATION_EVENT_KINDS.MODE_UPDATE,
+        payload,
+        {
+          timestamp,
+          sourceType: 'acp-mode-update'
+        }
+      );
+      return;
+    }
+
+    if (update.sessionUpdate === 'available_commands_update') {
+      this.emitConversationEvent(
+        CONVERSATION_EVENT_KINDS.AVAILABLE_COMMANDS_UPDATE,
+        normalizeAvailableCommandsUpdate(update),
+        {
+          timestamp,
+          sourceType: 'acp-available-commands-update'
+        }
+      );
+      return;
+    }
+
+    if (update.sessionUpdate === 'tool_call' || update.sessionUpdate === 'tool_call_update') {
+      const existing = this.streamState.toolCalls.get(update.toolCallId) || {
+        snapshotSignature: null,
+        resultSignature: null,
+        ended: false,
+        started: false,
+        toolName: null
+      };
+      const toolName = update.title || existing.toolName || 'Tool';
+      const toolPayload = buildToolCallConversationPayload(update, toolName);
+
+      if (!existing.started) {
+        // Tool calls should visually split assistant prose into before/after segments.
+        // Closing the current assistant message here lets post-tool text start a fresh block.
+        this.closeAssistantMessageBoundary(timestamp, 'acp-tool-boundary');
+        this.emitConversationEvent(
+          CONVERSATION_EVENT_KINDS.TOOL_CALL_START,
+          toolPayload,
+          {
+            timestamp,
+            sourceType: 'acp-tool-call'
+          }
+        );
+        existing.started = true;
+      }
+
+      const snapshotPayload = update.rawInput === undefined
+        ? toolPayload
+        : {
+            ...toolPayload,
+            input: cloneJsonValue(update.rawInput)
+          };
+      const snapshotSignature = normalizeComparableValue(snapshotPayload);
+      if (snapshotSignature !== existing.snapshotSignature) {
+        this.emitConversationEvent(
+          CONVERSATION_EVENT_KINDS.TOOL_CALL_INPUT,
+          snapshotPayload,
+          {
+            timestamp,
+            sourceType: 'acp-tool-call'
+          }
+        );
+        existing.snapshotSignature = snapshotSignature;
+      }
+
+      const isTerminalStatus = update.status === 'completed' || update.status === 'failed';
+      if (isTerminalStatus && !existing.ended) {
+        this.emitConversationEvent(
+          CONVERSATION_EVENT_KINDS.TOOL_CALL_END,
+          toolPayload,
+          {
+            timestamp,
+            sourceType: 'acp-tool-call'
+          }
+        );
+
+        const resultText = toToolContentText(update);
+        const resultSignature = normalizeComparableValue({
+          text: resultText,
+          rawOutput: update.rawOutput,
+          status: update.status,
+          content: update.content,
+          locations: update.locations
+        });
+
+        if (resultSignature !== existing.resultSignature) {
+          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) : []
+            },
+            {
+              timestamp,
+              sourceType: 'acp-tool-call'
+            }
+          );
+          existing.resultSignature = resultSignature;
+        }
+
+        existing.ended = true;
+      }
+
+      existing.toolName = toolName;
+      this.streamState.toolCalls.set(update.toolCallId, existing);
+    }
+  }
+
+  async start() {
+    if (this.connection) {
+      return this.initializeResult;
+    }
+
+    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,
+      env: spawnEnvironment.env
+    });
+
+    this.childProcess.stderr.on('data', (chunk) => {
+      const text = String(chunk || '').trim();
+      if (text) {
+        console.warn(`[ACP:${this.agentKey}] ${text}`);
+        this.handleAgentDiagnostic(text);
+      }
+    });
+
+    const stream = ndJsonStream(
+      Writable.toWeb(this.childProcess.stdin),
+      Readable.toWeb(this.childProcess.stdout)
+    );
+
+    this.connection = new ClientSideConnection(() => ({
+      requestPermission: (params) => this.handleRequestPermission(params),
+      sessionUpdate: (params) => this.handleSessionUpdate(params),
+      readTextFile: async (params) => {
+        const resolvedPath = path.isAbsolute(params.path)
+          ? params.path
+          : path.resolve(this.projectPath, params.path);
+        const content = await fs.readFile(resolvedPath, 'utf8');
+        return {
+          content: readLines(content, params.line, params.limit)
+        };
+      },
+      writeTextFile: async (params) => {
+        const resolvedPath = path.isAbsolute(params.path)
+          ? params.path
+          : path.resolve(this.projectPath, params.path);
+        await fs.mkdir(path.dirname(resolvedPath), { recursive: true });
+        await fs.writeFile(resolvedPath, params.content, 'utf8');
+        return {};
+      },
+      createTerminal: async (params) => {
+        const terminalId = `terminal:${randomUUID()}`;
+        const terminal = new LocalTerminalProcess({
+          sessionId: params.sessionId,
+          command: params.command,
+          args: params.args,
+          cwd: params.cwd || this.projectPath,
+          env: params.env,
+          outputByteLimit: params.outputByteLimit
+        });
+        this.terminalProcesses.set(terminalId, terminal);
+        return { terminalId };
+      },
+      terminalOutput: async (params) => {
+        return this.terminalProcesses.get(params.terminalId)?.currentOutput() || { output: '' };
+      },
+      waitForTerminalExit: async (params) => {
+        return this.terminalProcesses.get(params.terminalId)?.waitForExit() || {};
+      },
+      killTerminal: async (params) => {
+        const terminal = this.terminalProcesses.get(params.terminalId);
+        if (terminal) {
+          await terminal.kill();
+        }
+        return {};
+      },
+      releaseTerminal: async (params) => {
+        const terminal = this.terminalProcesses.get(params.terminalId);
+        if (terminal) {
+          await terminal.release();
+          this.terminalProcesses.delete(params.terminalId);
+        }
+        return {};
+      }
+    }), stream);
+
+    this.initializeResult = await this.connection.initialize({
+      protocolVersion: PROTOCOL_VERSION,
+      clientCapabilities: {
+        fs: {
+          readTextFile: true,
+          writeTextFile: true
+        },
+        terminal: true
+      },
+      clientInfo: {
+        name: '@axhub/genie',
+        title: 'Axhub Genie',
+        version: process.env.APP_VERSION || 'unknown'
+      }
+    });
+
+    return this.initializeResult;
+  }
+
+  async createSession() {
+    const response = await this.connection.newSession({
+      cwd: this.projectPath,
+      mcpServers: []
+    });
+
+    this.sessionId = response.sessionId;
+    this.attachWriter(this.writer);
+    const normalizedModes = normalizeSessionModeState(response?.modes);
+    this.emitPayload({
+      type: 'session-created',
+      modes: normalizedModes
+    });
+
+    if (normalizedModes) {
+      this.emitConversationEvent(
+        CONVERSATION_EVENT_KINDS.MODE_UPDATE,
+        normalizedModes,
+        {
+          timestamp: nowIso(),
+          sourceType: 'acp-session-created-modes'
+        }
+      );
+    }
+
+    if (this.model) {
+      await this.setModel(this.model);
+    }
+
+    return response;
+  }
+
+  async loadSession(sessionId, { suppressReplayUpdates = true } = {}) {
+    this.sessionId = String(sessionId || '').trim();
+    this.attachWriter(this.writer);
+    this.suppressSessionUpdates = Boolean(suppressReplayUpdates);
+    try {
+      const response = await this.connection.loadSession({
+        cwd: this.projectPath,
+        mcpServers: [],
+        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);
+      }
+
+      return response;
+    } finally {
+      this.suppressSessionUpdates = false;
+    }
+  }
+
+  async setModel(modelId) {
+    if (!modelId || !this.sessionId || !this.connection) {
+      return;
+    }
+
+    let lastError = null;
+
+    try {
+      if (typeof this.connection.setSessionConfigOption === 'function') {
+        try {
+          await this.connection.setSessionConfigOption({
+            sessionId: this.sessionId,
+            configId: 'model',
+            value: modelId
+          });
+          return;
+        } catch (error) {
+          lastError = error;
+        }
+      }
+
+      if (typeof this.connection.unstable_setSessionModel === 'function') {
+        try {
+          await this.connection.unstable_setSessionModel({
+            sessionId: this.sessionId,
+            modelId
+          });
+          return;
+        } catch (error) {
+          lastError = error;
+        }
+      }
+    } catch (error) {
+      lastError = error;
+    }
+
+    if (lastError) {
+      console.warn(`[ACP:${this.agentKey}] Failed to set model "${modelId}": ${lastError.message}`);
+    }
+  }
+
+  async setMode(modeId) {
+    const normalizedModeId = String(modeId || '').trim();
+    if (!normalizedModeId || !this.sessionId || !this.connection?.setSessionMode) {
+      return false;
+    }
+
+    await this.connection.setSessionMode({
+      sessionId: this.sessionId,
+      modeId: normalizedModeId
+    });
+    return true;
+  }
+
+  async sendPrompt(promptText, attachments = {}) {
+    this.resetTurnState();
+    this.hasReportedPromptFatalError = false;
+    this.agentDiagnosticBuffer = '';
+    const promptPayload = buildPromptBlocks(promptText, attachments);
+    const clientRequestId = typeof attachments?.clientRequestId === 'string' && attachments.clientRequestId.trim()
+      ? attachments.clientRequestId.trim()
+      : null;
+
+    this.emitConversationEvent(
+      CONVERSATION_EVENT_KINDS.USER_MESSAGE,
+      {
+        text: promptPayload.text,
+        contentBlocks: promptPayload.contentBlocks
+      },
+      {
+        timestamp: nowIso(),
+        sourceType: 'acp-user-prompt',
+        extensions: clientRequestId ? { clientRequestId } : {}
+      }
+    );
+
+    this.emitConversationEvent(
+      CONVERSATION_EVENT_KINDS.SESSION_STATE_CHANGED,
+      {
+        state: 'queued'
+      },
+      {
+        timestamp: nowIso(),
+        sourceType: 'acp-prompt-start'
+      }
+    );
+
+    this.emitPayload({
+      type: 'session-status',
+      isProcessing: true
+    });
+
+    this.isPromptInFlight = true;
+    let diagnosticGuard = null;
+    const diagnosticPromise = new Promise((_, reject) => {
+      diagnosticGuard = {
+        handled: false,
+        reject
+      };
+      this.pendingPromptDiagnostic = diagnosticGuard;
+    });
+
+    const promptPromise = this.connection.prompt({
+      sessionId: this.sessionId,
+      prompt: promptPayload.blocks
+    });
+    promptPromise.catch(() => {});
+
+    try {
+      const response = await Promise.race([promptPromise, diagnosticPromise]);
+      const finishedAt = nowIso();
+      this.flushOpenTextStreams(finishedAt);
+      this.emitConversationEvent(
+        CONVERSATION_EVENT_KINDS.SESSION_STATE_CHANGED,
+        {
+          state: response?.stopReason === 'cancelled' ? 'aborted' : 'completed',
+          stopReason: response?.stopReason || null
+        },
+        {
+          timestamp: finishedAt,
+          sourceType: 'acp-prompt-complete'
+        }
+      );
+
+      this.emitPayload({
+        type: 'session-status',
+        isProcessing: false
+      });
+
+      return response;
+    } catch (error) {
+      this.reportPromptFailure(error);
+      throw error;
+    } finally {
+      this.isPromptInFlight = false;
+      if (this.pendingPromptDiagnostic === diagnosticGuard) {
+        this.pendingPromptDiagnostic = null;
+      }
+    }
+  }
+
+  async cancel(sessionId = this.sessionId) {
+    const normalizedSessionId = String(sessionId || this.sessionId || '').trim();
+    if (!normalizedSessionId) {
+      return false;
+    }
+
+    for (const requestId of this.pendingPermissionIds) {
+      AcpClient.resolvePermissionRequest(requestId, { cancelled: true });
+    }
+
+    try {
+      await this.connection.cancel({
+        sessionId: normalizedSessionId
+      });
+      this.emitPayload({
+        type: 'session-aborted',
+        success: true
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async close() {
+    for (const requestId of this.pendingPermissionIds) {
+      AcpClient.resolvePermissionRequest(requestId, { cancelled: true });
+    }
+
+    for (const [terminalId, terminal] of this.terminalProcesses.entries()) {
+      try {
+        await terminal.release();
+      } catch {}
+      this.terminalProcesses.delete(terminalId);
+    }
+
+    if (this.childProcess && !this.childProcess.killed) {
+      if (!this.childProcess.stdin.destroyed) {
+        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);
+        });
+      });
+
+      if (!closed) {
+        try {
+          this.childProcess.kill('SIGTERM');
+        } catch {}
+      }
+    }
+
+    if (this.spawnCleanup) {
+      try {
+        await this.spawnCleanup();
+      } catch {}
+      this.spawnCleanup = null;
+    }
+
+    this.connection = null;
+    this.childProcess = null;
+    this.initializeResult = null;
+  }
+
+  static resolvePermissionRequest(requestId, decision = {}) {
+    const pending = pendingPermissionRequests.get(requestId);
+    if (!pending) {
+      return false;
+    }
+
+    pending.resolve(choosePermissionResponse(pending.request, decision));
+    return true;
+  }
+}
+
+export { normalizeTerminalCommandForSpawn };