@axhub/genie 0.2.10 → 0.2.12

package/server/session-core/providerAdapters.js

@@ -1,209 +1,690 @@
-import { normalizeLegacyHistoryEntries, SUPPORTED_PROVIDERS } from '../../shared/conversationEvents.js';
-import { mergeConversationEventHistories, readMirroredConversationEvents } from './eventStore.js';
 import {
-  getSessionMessages,
-  getCodexSessionMessages,
-  getOpencodeSessionMessages,
-  getGeminiSessionMessages,
-  getSessions,
-  getCodexSessions,
-  getOpencodeSessions,
-  getGeminiSessions
-} from '../projects.js';
+  isConversationEvent,
+  SUPPORTED_PROVIDERS
+} from '../../shared/conversationEvents.js';
+import {
+  disposeManagedAgentClient,
+  getOrStartAgentClient,
+  isAgentSessionActive,
+  retainSessionAgentClient,
+  shouldSkipGeminiAutomaticAcpStartup
+} from '../acp-runtime/index.js';
+import { mergeAgentCommandOverrides } from '../acp-runtime/command-overrides.js';
 import {
   findAcpSessionRecord,
-  listAcpSessions
+  listAcpSessions,
+  touchAcpSessionRecord
 } from '../acp-runtime/session-store.js';
-import { mergeSessionLists } from './sessionListMerge.js';
 
-async function flattenLegacyMessages(result) {
-  if (Array.isArray(result)) return result;
-  return Array.isArray(result?.messages) ? result.messages : [];
+function getAgentCommandOverrides(options = {}) {
+  return mergeAgentCommandOverrides(
+    process.env.AXHUB_ACP_COMMAND_OVERRIDES,
+    options.agentCommandOverrides
+  );
+}
+
+function createAcpReplayWriter() {
+  const events = [];
+
+  return {
+    events,
+    send(payload) {
+      if (payload?.type === 'conversation-event' && isConversationEvent(payload.event)) {
+        events.push(payload.event);
+      }
+    },
+    setSessionId() {},
+    getSessionId() {
+      return null;
+    }
+  };
+}
+
+const acpSessionEventCache = new Map();
+
+function createSessionEventCacheKey(provider, sessionId) {
+  const normalizedProvider = normalizeProvider(provider);
+  const normalizedSessionId = normalizeSessionId(sessionId);
+  if (!normalizedProvider || !normalizedSessionId) {
+    return null;
+  }
+  return `${normalizedProvider}:${normalizedSessionId}`;
+}
+
+function cloneJsonValue(value) {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  return JSON.parse(JSON.stringify(value));
+}
+
+function normalizeComparableText(value) {
+  return String(value || '').replace(/\r\n/g, '\n').trim();
+}
+
+function getEventMessageId(event) {
+  const rawValue = event?.payload?.messageId || event?.extensions?.messageId || null;
+  return typeof rawValue === 'string' && rawValue.trim() ? rawValue.trim() : null;
+}
+
+function getUserMessageText(event) {
+  return event?.kind === 'user_message'
+    ? normalizeComparableText(event?.payload?.text)
+    : '';
+}
+
+function isReplayEvent(event) {
+  return Boolean(
+    event?.extensions?.runtimeReplay === true ||
+    event?.rawRef?.sourceType === 'acp-session-loaded-replay'
+  );
+}
+
+function getReplayOriginalTimestamp(event) {
+  const rawValue = event?.extensions?.originalTimestamp || event?.payload?.originalTimestamp || null;
+  if (typeof rawValue !== 'string' || !rawValue.trim()) {
+    return null;
+  }
+
+  const parsed = Date.parse(rawValue);
+  return Number.isFinite(parsed) ? rawValue : null;
+}
+
+function getEventSortTime(event) {
+  const replayTimestamp = isReplayEvent(event) ? getReplayOriginalTimestamp(event) : null;
+  const parsed = Date.parse(replayTimestamp || event?.timestamp || '');
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+function getEventOrderRank(event) {
+  if (event?.kind === 'user_message') {
+    return 0;
+  }
+  if (
+    event?.kind === 'assistant_text_start' ||
+    event?.kind === 'assistant_text_delta' ||
+    event?.kind === 'assistant_text_end' ||
+    event?.kind === 'reasoning_start' ||
+    event?.kind === 'reasoning_delta' ||
+    event?.kind === 'reasoning_end'
+  ) {
+    return 1;
+  }
+  if (event?.kind === 'tool_call_start' || event?.kind === 'tool_call_input') {
+    return 2;
+  }
+  if (event?.kind === 'tool_call_end' || event?.kind === 'tool_result') {
+    return 3;
+  }
+  return 4;
+}
+
+function buildEventSignature(event) {
+  return JSON.stringify({
+    kind: event.kind,
+    provider: event.provider,
+    sessionId: event.sessionId,
+    payload: event.payload || {},
+    extensions: event.extensions || {},
+    rawRef: event.rawRef || null
+  });
 }
 
-function hasReplayableTranscriptContent(events = []) {
-  return (Array.isArray(events) ? events : []).some((event) => (
-    event?.kind === 'user_message' ||
+function getEventTieBreakerKey(event) {
+  if (event?.kind === 'user_message') {
+    return getUserMessageText(event);
+  }
+  if (
+    event?.kind === 'assistant_text_start' ||
     event?.kind === 'assistant_text_delta' ||
-    event?.kind === 'assistant_content_block' ||
+    event?.kind === 'assistant_text_end' ||
+    event?.kind === 'reasoning_start' ||
     event?.kind === 'reasoning_delta' ||
-    event?.kind === 'tool_call_start' ||
-    event?.kind === 'tool_result' ||
-    event?.kind === 'plan_update' ||
-    event?.kind === 'system_notice'
-  ));
+    event?.kind === 'reasoning_end'
+  ) {
+    return typeof event?.payload?.messageId === 'string' ? event.payload.messageId : '';
+  }
+  return '';
 }
 
-async function normalizeLegacyLoadResult(result, provider, sessionId) {
-  const messages = await flattenLegacyMessages(result);
-  const legacyEvents = normalizeLegacyHistoryEntries(messages, provider, sessionId);
-  const mirroredEvents = await readMirroredConversationEvents(provider, sessionId);
-  const events = mergeConversationEventHistories(legacyEvents, mirroredEvents);
+function createEventIdentityKey(event) {
+  if (event?.eventId) {
+    return `id:${event.eventId}`;
+  }
+
+  return `signature:${buildEventSignature(event)}`;
+}
 
-  if (Array.isArray(result)) {
-    return events;
+function findNearestUserTextBeforeIndex(events = [], index = -1) {
+  for (let i = index - 1; i >= 0; i -= 1) {
+    const userText = getUserMessageText(events[i]);
+    if (userText) {
+      return userText;
+    }
   }
 
-  return {
-    ...result,
-    events,
-    source: 'legacy'
+  return '';
+}
+
+function shouldTreatUserMessagesAsDuplicates(leftEvent, rightEvent) {
+  if (leftEvent?.kind !== 'user_message' || rightEvent?.kind !== 'user_message') {
+    return false;
+  }
+
+  const leftText = getUserMessageText(leftEvent);
+  const rightText = getUserMessageText(rightEvent);
+  if (!leftText || leftText !== rightText) {
+    return false;
+  }
+
+  const leftClientRequestId = leftEvent?.extensions?.clientRequestId || null;
+  const rightClientRequestId = rightEvent?.extensions?.clientRequestId || null;
+  if (leftClientRequestId && rightClientRequestId && leftClientRequestId === rightClientRequestId) {
+    return true;
+  }
+
+  return isReplayEvent(leftEvent) || isReplayEvent(rightEvent);
+}
+
+function collectAssistantTextGroups(events = []) {
+  const groupsByMessageId = new Map();
+  const groups = [];
+  let lastUserText = '';
+
+  const ensureGroup = (event) => {
+    const messageId = getEventMessageId(event) || `anonymous:${groups.length}`;
+    let group = groupsByMessageId.get(messageId);
+    if (!group) {
+      group = {
+        messageId,
+        userText: lastUserText,
+        events: [],
+        text: '',
+      };
+      groupsByMessageId.set(messageId, group);
+      groups.push(group);
+    }
+    return group;
   };
+
+  for (const event of Array.isArray(events) ? events : []) {
+    if (!isConversationEvent(event)) {
+      continue;
+    }
+
+    const userText = getUserMessageText(event);
+    if (userText) {
+      lastUserText = userText;
+      continue;
+    }
+
+    if (
+      event.kind !== 'assistant_text_start' &&
+      event.kind !== 'assistant_text_delta' &&
+      event.kind !== 'assistant_text_end'
+    ) {
+      continue;
+    }
+
+    const group = ensureGroup(event);
+    group.events.push(event);
+    if (event.kind === 'assistant_text_delta') {
+      group.text += String(event.payload?.text || '');
+    }
+  }
+
+  return groups
+    .map((group) => ({
+      ...group,
+      text: normalizeComparableText(group.text),
+    }))
+    .filter((group) => group.text);
 }
 
-function createEventLoadResult(events = [], source = 'acp') {
+function findMatchingUserEventIndex(events, userText) {
+  const normalizedUserText = normalizeComparableText(userText);
+  if (!normalizedUserText) {
+    return -1;
+  }
+
+  return events.findIndex((event) => getUserMessageText(event) === normalizedUserText);
+}
+
+function insertEventsAfterMatchingUser(events, userText, eventsToInsert) {
+  const insertIndex = findMatchingUserEventIndex(events, userText);
+  if (insertIndex < 0) {
+    return [...events, ...eventsToInsert];
+  }
+
+  return [
+    ...events.slice(0, insertIndex + 1),
+    ...eventsToInsert,
+    ...events.slice(insertIndex + 1),
+  ];
+}
+
+function relocateCachedAssistantGroupsAfterMatchingUsers(events = [], cachedEvents = []) {
+  let relocatedEvents = Array.isArray(events) ? events : [];
+
+  for (const cachedGroup of collectAssistantTextGroups(cachedEvents)) {
+    const normalizedUserText = normalizeComparableText(cachedGroup.userText);
+    if (!normalizedUserText) {
+      continue;
+    }
+
+    const groupKeys = new Set(
+      cachedGroup.events.map(createEventIdentityKey).filter(Boolean)
+    );
+    if (groupKeys.size === 0) {
+      continue;
+    }
+
+    const groupIndexes = [];
+    relocatedEvents.forEach((event, index) => {
+      if (groupKeys.has(createEventIdentityKey(event))) {
+        groupIndexes.push(index);
+      }
+    });
+    if (groupIndexes.length === 0) {
+      continue;
+    }
+
+    const firstGroupIndex = groupIndexes[0];
+    if (findNearestUserTextBeforeIndex(relocatedEvents, firstGroupIndex) === normalizedUserText) {
+      continue;
+    }
+
+    const groupIndexSet = new Set(groupIndexes);
+    const groupEvents = groupIndexes.map((index) => relocatedEvents[index]);
+    const eventsWithoutGroup = relocatedEvents.filter((_, index) => !groupIndexSet.has(index));
+    relocatedEvents = insertEventsAfterMatchingUser(
+      eventsWithoutGroup,
+      normalizedUserText,
+      groupEvents
+    );
+  }
+
+  return relocatedEvents;
+}
+
+function mergeCachedAssistantReplayEvents(currentEvents = [], cachedEvents = []) {
+  const normalizedCurrentEvents = (Array.isArray(currentEvents) ? currentEvents : []).filter(isConversationEvent);
+  const normalizedCachedEvents = (Array.isArray(cachedEvents) ? cachedEvents : []).filter(isConversationEvent);
+
+  if (normalizedCurrentEvents.length === 0) {
+    return normalizedCachedEvents.map(cloneJsonValue);
+  }
+
+  let mergedEvents = normalizedCurrentEvents.map(cloneJsonValue);
+  const mergedEventIds = new Set(
+    mergedEvents.map((event) => event.eventId).filter(Boolean)
+  );
+  const mergedEventSignatures = new Set(
+    mergedEvents.map(buildEventSignature)
+  );
+
+  for (const cachedEvent of normalizedCachedEvents) {
+    if (cachedEvent?.eventId && mergedEventIds.has(cachedEvent.eventId)) {
+      continue;
+    }
+
+    if (
+      cachedEvent.kind === 'user_message' &&
+      mergedEvents.some((event) => shouldTreatUserMessagesAsDuplicates(event, cachedEvent))
+    ) {
+      continue;
+    }
+
+    const signature = buildEventSignature(cachedEvent);
+    if (mergedEventSignatures.has(signature)) {
+      continue;
+    }
+
+    mergedEvents.push(cloneJsonValue(cachedEvent));
+    if (cachedEvent?.eventId) {
+      mergedEventIds.add(cachedEvent.eventId);
+    }
+    mergedEventSignatures.add(signature);
+  }
+
+  mergedEvents = mergedEvents.map((event, index) => ({ event, index }));
+  mergedEvents.sort((leftEntry, rightEntry) => {
+    const left = leftEntry.event;
+    const right = rightEntry.event;
+    const leftTime = getEventSortTime(left);
+    const rightTime = getEventSortTime(right);
+    if (leftTime !== rightTime) {
+      return leftTime - rightTime;
+    }
+    const rankDelta = getEventOrderRank(left) - getEventOrderRank(right);
+    if (rankDelta !== 0) {
+      const leftKey = getEventTieBreakerKey(left);
+      const rightKey = getEventTieBreakerKey(right);
+      if (leftKey && rightKey && leftKey === rightKey) {
+        return rankDelta;
+      }
+    }
+    return leftEntry.index - rightEntry.index;
+  });
+  mergedEvents = mergedEvents.map((entry) => entry.event);
+  mergedEvents = relocateCachedAssistantGroupsAfterMatchingUsers(
+    mergedEvents,
+    normalizedCachedEvents
+  );
+
+  const currentAssistantTexts = new Set(
+    collectAssistantTextGroups(mergedEvents)
+      .map((group) => group.text)
+      .filter(Boolean)
+  );
+
+  for (const cachedGroup of collectAssistantTextGroups(normalizedCachedEvents)) {
+    if (currentAssistantTexts.has(cachedGroup.text)) {
+      continue;
+    }
+
+    mergedEvents = insertEventsAfterMatchingUser(
+      mergedEvents,
+      cachedGroup.userText,
+      cachedGroup.events.map(cloneJsonValue)
+    );
+    currentAssistantTexts.add(cachedGroup.text);
+  }
+
+  return mergedEvents;
+}
+
+function readCachedSessionEvents(provider, sessionId) {
+  const cacheKey = createSessionEventCacheKey(provider, sessionId);
+  if (!cacheKey) {
+    return [];
+  }
+
+  return (acpSessionEventCache.get(cacheKey) || []).map(cloneJsonValue);
+}
+
+function rememberSessionEvents(provider, sessionId, events = []) {
+  const cacheKey = createSessionEventCacheKey(provider, sessionId);
+  if (!cacheKey) {
+    return Array.isArray(events) ? events : [];
+  }
+
+  const mergedEvents = mergeCachedAssistantReplayEvents(events, acpSessionEventCache.get(cacheKey) || []);
+  acpSessionEventCache.set(cacheKey, mergedEvents.map(cloneJsonValue));
+  return mergedEvents.map(cloneJsonValue);
+}
+
+function paginateEventsFromTail(events = [], limit = null, offset = 0) {
   const normalizedEvents = Array.isArray(events) ? events : [];
+  const normalizedLimit = limit === null ? null : Math.max(0, Number(limit) || 0);
+  const normalizedOffset = Math.max(0, Number(offset) || 0);
+  const total = normalizedEvents.length;
+
+  if (normalizedLimit === null) {
+    return {
+      events: normalizedEvents,
+      total,
+      hasMore: false,
+      offset: 0,
+      limit: null
+    };
+  }
+
+  const endIndex = Math.max(0, total - normalizedOffset);
+  const startIndex = Math.max(0, endIndex - normalizedLimit);
+  const paginatedEvents = normalizedEvents.slice(startIndex, endIndex);
+
   return {
-    events: normalizedEvents,
-    total: normalizedEvents.length,
-    hasMore: false,
-    offset: 0,
-    limit: null,
+    events: paginatedEvents,
+    total,
+    hasMore: total > normalizedOffset + paginatedEvents.length,
+    offset: normalizedOffset,
+    limit: normalizedLimit
+  };
+}
+
+function createEventLoadResult(events = [], source = 'acp', options = {}) {
+  return {
+    ...paginateEventsFromTail(events, options.limit, options.offset),
     source
   };
 }
 
-async function loadAcpEvents(provider, sessionId, nativeHistoryLoader = null) {
-  const record = await findAcpSessionRecord(sessionId, provider);
-  if (!record) {
+function getLastEventTimestamp(events = []) {
+  const timestamps = (Array.isArray(events) ? events : [])
+    .map((event) => Date.parse(event?.timestamp || ''))
+    .filter(Number.isFinite);
+  if (timestamps.length === 0) {
     return null;
   }
+  return new Date(Math.max(...timestamps)).toISOString();
+}
 
-  const mirroredEvents = await readMirroredConversationEvents(provider, sessionId);
-  if (hasReplayableTranscriptContent(mirroredEvents)) {
-    return createEventLoadResult(mirroredEvents, 'acp');
+function getLastUserEventTimestamp(events = []) {
+  const timestamps = (Array.isArray(events) ? events : [])
+    .filter((event) => event?.kind === 'user_message')
+    .map((event) => Date.parse(event?.timestamp || ''))
+    .filter(Number.isFinite);
+  if (timestamps.length === 0) {
+    return null;
   }
+  return new Date(Math.max(...timestamps)).toISOString();
+}
 
-  if (typeof nativeHistoryLoader === 'function') {
-    try {
-      const nativeResult = await nativeHistoryLoader();
-      const normalizedResult = await normalizeLegacyLoadResult(nativeResult, provider, sessionId);
-      if (Array.isArray(normalizedResult)) {
-        return createEventLoadResult(normalizedResult, 'acp');
-      }
-      return {
-        ...normalizedResult,
-        source: 'acp'
-      };
-    } catch {
-      // Fall back to the mirrored event store when native history is unavailable.
-    }
+function isAcpMissingResourceError(error) {
+  const message = String(error?.message || error || '').trim().toLowerCase();
+  return message === 'resource not found'
+    || message.includes('resource not found')
+    || message.includes('session not found');
+}
+
+function getSessionActivityTime(session) {
+  return new Date(
+    session?.lastActivity
+    || session?.updatedAt
+    || session?.updated_at
+    || session?.createdAt
+    || session?.created_at
+    || 0
+  ).getTime();
+}
+
+function normalizeSessionId(value) {
+  const normalized = String(value || '').trim();
+  return normalized || null;
+}
+
+function normalizeProvider(value) {
+  return String(value || '').trim().toLowerCase();
+}
+
+const GENERIC_ACP_SESSION_TITLE_PATTERN = /^ACP Session\b/i;
+
+function isProbeLikeAcpSession(session) {
+  if (!session || session.source !== 'acp') {
+    return false;
   }
 
-  return createEventLoadResult(mirroredEvents, 'acp');
+  const lastPromptAt = String(session?.lastPromptAt || '').trim();
+  if (lastPromptAt) {
+    return false;
+  }
+
+  const title = String(session?.title || '').trim();
+  const summary = String(session?.summary || '').trim();
+
+  return GENERIC_ACP_SESSION_TITLE_PATTERN.test(title)
+    || GENERIC_ACP_SESSION_TITLE_PATTERN.test(summary);
 }
 
-const PROVIDER_ADAPTERS = {
-  claude: {
-    async listSessions({ projectName, projectPath, limit = 50, offset = 0 }) {
-      const [result, acpSessions] = await Promise.all([
-        getSessions(projectName, limit, offset),
-        listAcpSessions({ provider: 'claude', projectPath: projectPath || null })
-      ]);
-      return mergeSessionLists(
-        (result?.sessions || []).map((session) => ({ ...session, provider: 'claude', source: 'legacy' })),
-        acpSessions,
-        { fallbackProvider: 'claude' }
-      );
-    },
-    async loadEvents({ projectName, sessionId, limit = null, offset = 0 }) {
-      const acpResult = await loadAcpEvents(
-        'claude',
-        sessionId,
-        () => getSessionMessages(projectName, sessionId, limit, offset),
-      );
-      if (acpResult) {
-        return acpResult;
-      }
+function createSnapshotOverlay(snapshot) {
+  if (!snapshot || typeof snapshot !== 'object') {
+    return {};
+  }
 
-      const rawMessages = await getSessionMessages(projectName, sessionId, limit, offset);
-      return normalizeLegacyLoadResult(rawMessages, 'claude', sessionId);
-    }
-  },
-  codex: {
-    async listSessions({ projectPath, limit = 50 }) {
-      const [sessions, acpSessions] = await Promise.all([
-        getCodexSessions(projectPath, { limit }),
-        listAcpSessions({ provider: 'codex', projectPath: projectPath || null })
-      ]);
-      return mergeSessionLists(
-        sessions.map((session) => ({ ...session, provider: 'codex', source: 'legacy' })),
-        acpSessions,
-        { fallbackProvider: 'codex' }
-      );
-    },
-    async loadEvents({ sessionId, limit = null, offset = 0 }) {
-      const acpResult = await loadAcpEvents(
-        'codex',
-        sessionId,
-        () => getCodexSessionMessages(sessionId, limit, offset),
-      );
-      if (acpResult) {
-        return acpResult;
-      }
+  const overlay = {};
+  const copyIfPresent = (targetKey, sourceKey = targetKey) => {
+    if (snapshot[sourceKey] !== undefined && snapshot[sourceKey] !== null) {
+      overlay[targetKey] = snapshot[sourceKey];
+    }
+  };
 
-      const rawMessages = await getCodexSessionMessages(sessionId, limit, offset);
-      return normalizeLegacyLoadResult(rawMessages, 'codex', sessionId);
-    }
-  },
-  gemini: {
-    async listSessions({ projectPath, limit = 50 }) {
-      const [sessions, acpSessions] = await Promise.all([
-        getGeminiSessions(projectPath, { limit }),
-        listAcpSessions({ provider: 'gemini', projectPath: projectPath || null })
-      ]);
-      return mergeSessionLists(
-        sessions.map((session) => ({ ...session, provider: 'gemini', source: 'legacy' })),
-        acpSessions,
-        { fallbackProvider: 'gemini' }
-      );
-    },
-    async loadEvents({ sessionId, limit = null, offset = 0 }) {
-      const acpResult = await loadAcpEvents(
-        'gemini',
-        sessionId,
-        () => getGeminiSessionMessages(sessionId, limit, offset),
-      );
-      if (acpResult) {
-        return acpResult;
-      }
+  copyIfPresent('title');
+  copyIfPresent('summary');
+  copyIfPresent('model');
+  copyIfPresent('createdAt');
+  copyIfPresent('updatedAt');
+  copyIfPresent('lastActivity');
+  copyIfPresent('lastPromptAt');
+  copyIfPresent('closedAt');
+  copyIfPresent('isClosed');
+  copyIfPresent('projectPath');
+  copyIfPresent('cwd', 'projectPath');
 
-      const rawMessages = await getGeminiSessionMessages(sessionId, limit, offset);
-      return normalizeLegacyLoadResult(rawMessages, 'gemini', sessionId);
-    }
-  },
-  opencode: {
-    async listSessions({ projectPath, limit = 50 }) {
-      const [sessions, acpSessions] = await Promise.all([
-        getOpencodeSessions(projectPath, { limit }),
-        listAcpSessions({ provider: 'opencode', projectPath: projectPath || null })
-      ]);
-      return mergeSessionLists(
-        sessions.map((session) => ({ ...session, provider: 'opencode', source: 'legacy' })),
-        acpSessions,
-        { fallbackProvider: 'opencode' }
-      );
-    },
-    async loadEvents({ sessionId, limit = null, offset = 0 }) {
-      const acpResult = await loadAcpEvents(
-        'opencode',
-        sessionId,
-        () => getOpencodeSessionMessages(sessionId, limit, offset),
-      );
-      if (acpResult) {
-        return acpResult;
+  return overlay;
+}
+
+async function listAcpSessionsWithSnapshotOverlay(provider, options = {}) {
+  const { projectPath, limit = 50 } = options;
+  const snapshots = await listAcpSessions({ provider, projectPath: projectPath || null });
+  const sessions = snapshots
+    .map((session) => ({
+      ...session,
+      ...createSnapshotOverlay(session),
+      provider,
+      __provider: provider,
+      source: 'acp',
+      runtime: 'acp'
+    }))
+    .filter((session) => !isProbeLikeAcpSession(session))
+    .sort((left, right) => getSessionActivityTime(right) - getSessionActivityTime(left));
+
+  return limit > 0 ? sessions.slice(0, limit) : sessions;
+}
+
+async function loadAcpEvents(provider, sessionId, options = {}) {
+  const record = await findAcpSessionRecord(sessionId, provider);
+  const projectPath = record?.projectPath || options.projectPath || null;
+  const cachedEvents = readCachedSessionEvents(provider, sessionId);
+  if (isAgentSessionActive(provider, sessionId)) {
+    return createEventLoadResult(cachedEvents, 'acp', options);
+  }
+
+  if (!projectPath) {
+    return createEventLoadResult(cachedEvents, 'acp', options);
+  }
+
+  if (await shouldSkipGeminiAutomaticAcpStartup(provider, options)) {
+    return createEventLoadResult(cachedEvents, 'acp', options);
+  }
+
+  const writer = createAcpReplayWriter();
+  const { client, reused } = await getOrStartAgentClient({
+    agentKey: provider,
+    writer,
+    projectPath,
+    sessionId,
+    options: {
+      agentCommandOverrides: getAgentCommandOverrides(options)
+    }
+  });
+  let shouldRetainClient = false;
+  const shouldDisposeOnFailure = reused !== 'session';
+
+  try {
+    if (!client.canLoadSession()) {
+      return createEventLoadResult(cachedEvents, 'acp', options);
+    }
+
+    let response;
+    try {
+      response = await client.loadSession(sessionId, { suppressReplayUpdates: false });
+    } catch (error) {
+      if (isAcpMissingResourceError(error)) {
+        return createEventLoadResult(cachedEvents, 'acp', options);
       }
+      console.warn(`Could not replay ${provider} ACP session ${sessionId}:`, error.message);
+      return createEventLoadResult(cachedEvents, 'acp', options);
+    }
+    shouldRetainClient = true;
+
+    const mergedEvents = rememberSessionEvents(provider, sessionId, writer.events);
+    await touchAcpSessionRecord({
+      provider,
+      sessionId,
+      projectPath,
+      title: record?.title || sessionId,
+      summary: record?.summary || null,
+      model: record?.model || client.model || null,
+      lastActivity: getLastEventTimestamp(mergedEvents) || record?.lastActivity || new Date().toISOString(),
+      lastPromptAt: getLastUserEventTimestamp(mergedEvents) || record?.lastPromptAt || null,
+      isClosed: record?.isClosed ?? false
+    });
+    const result = createEventLoadResult(mergedEvents, 'acp', options);
 
-      const rawMessages = await getOpencodeSessionMessages(sessionId, limit, offset);
-      return normalizeLegacyLoadResult(rawMessages, 'opencode', sessionId);
+    if (response?.tokenUsage) {
+      result.tokenUsage = response.tokenUsage;
+    }
+
+    return result;
+  } finally {
+    if (shouldRetainClient) {
+      retainSessionAgentClient({
+        provider,
+        sessionId,
+        client,
+        metadata: {
+          projectPath
+        }
+      });
+    } else if (shouldDisposeOnFailure) {
+      await disposeManagedAgentClient({
+        provider,
+        sessionId,
+        projectPath,
+        client
+      });
+    } else {
+      retainSessionAgentClient({
+        provider,
+        sessionId,
+        client,
+        metadata: {
+          projectPath
+        }
+      });
     }
   }
-};
+}
+
+function createProviderAdapter(provider) {
+  return {
+    async listSessions({ projectPath, limit = 50, agentCommandOverrides = {} } = {}) {
+      try {
+        return await listAcpSessionsWithSnapshotOverlay(provider, { projectPath, limit, agentCommandOverrides });
+      } catch (error) {
+        console.warn(`Could not load ${provider} ACP sessions for project ${projectPath}:`, error.message);
+        return [];
+      }
+    },
+    async loadEvents({ sessionId, projectPath, limit = null, offset = 0, agentCommandOverrides = {} } = {}) {
+      return loadAcpEvents(provider, sessionId, { projectPath, limit, offset, agentCommandOverrides });
+    }
+  };
+}
+
+const PROVIDER_ADAPTERS = SUPPORTED_PROVIDERS.reduce((adapters, provider) => {
+  adapters[provider] = createProviderAdapter(provider);
+  return adapters;
+}, {});
 
 export function getProviderAdapter(provider) {
-  const normalizedProvider = String(provider || '').toLowerCase();
+  const normalizedProvider = normalizeProvider(provider);
   if (!SUPPORTED_PROVIDERS.includes(normalizedProvider)) {
     throw new Error(`Unsupported provider: ${provider}`);
   }
   return PROVIDER_ADAPTERS[normalizedProvider];
 }
+
+export const __test__rememberSessionEvents = rememberSessionEvents;