@axhub/genie 0.1.8 → 0.1.9

package/shared/conversationEvents.js

@@ -0,0 +1,1031 @@
+export const SUPPORTED_PROVIDERS = ['claude', 'codex', 'gemini', 'opencode'];
+
+export const SESSION_STATES = [
+  'discovering_history',
+  'hydrating',
+  'idle',
+  'streaming',
+  'awaiting_approval',
+  'completed',
+  'aborted',
+  'errored'
+];
+
+export const CONVERSATION_EVENT_KINDS = {
+  USER_MESSAGE: 'user_message',
+  ASSISTANT_TEXT_START: 'assistant_text_start',
+  ASSISTANT_TEXT_DELTA: 'assistant_text_delta',
+  ASSISTANT_TEXT_END: 'assistant_text_end',
+  REASONING_START: 'reasoning_start',
+  REASONING_DELTA: 'reasoning_delta',
+  REASONING_END: 'reasoning_end',
+  TOOL_CALL_START: 'tool_call_start',
+  TOOL_CALL_INPUT: 'tool_call_input',
+  TOOL_CALL_END: 'tool_call_end',
+  TOOL_RESULT: 'tool_result',
+  APPROVAL_REQUEST: 'approval_request',
+  APPROVAL_RESOLVED: 'approval_resolved',
+  ARTIFACT_CREATED: 'artifact_created',
+  SESSION_STATE_CHANGED: 'session_state_changed',
+  SYSTEM_NOTICE: 'system_notice',
+  ERROR: 'error'
+};
+
+function createEventId(prefix = 'evt') {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return `${prefix}:${crypto.randomUUID()}`;
+  }
+  return `${prefix}:${Date.now()}:${Math.random().toString(36).slice(2, 10)}`;
+}
+
+function normalizeTimestamp(timestamp) {
+  if (!timestamp) return new Date().toISOString();
+  if (timestamp instanceof Date) return timestamp.toISOString();
+  const parsed = new Date(timestamp);
+  if (Number.isNaN(parsed.getTime())) return new Date().toISOString();
+  return parsed.toISOString();
+}
+
+export function createConversationEvent({
+  kind,
+  provider = 'claude',
+  sessionId = null,
+  timestamp,
+  payload = {},
+  extensions = {},
+  rawRef = null,
+  eventId = null
+}) {
+  return {
+    eventId: eventId || createEventId(kind),
+    kind,
+    provider,
+    sessionId,
+    timestamp: normalizeTimestamp(timestamp),
+    payload,
+    extensions,
+    rawRef
+  };
+}
+
+export function isConversationEvent(value) {
+  return !!(
+    value &&
+    typeof value === 'object' &&
+    typeof value.kind === 'string' &&
+    typeof value.eventId === 'string'
+  );
+}
+
+export function createTextSpanEvents({
+  kindPrefix = 'assistant_text',
+  text,
+  provider,
+  sessionId,
+  timestamp,
+  messageId,
+  extensions = {},
+  rawRef = null
+}) {
+  if (typeof text !== 'string' || !text.trim()) return [];
+  const id = messageId || createEventId(kindPrefix);
+  const normalizedExtensions = { ...extensions, messageId: id };
+
+  return [
+    createConversationEvent({
+      kind: `${kindPrefix}_start`,
+      provider,
+      sessionId,
+      timestamp,
+      payload: { messageId: id },
+      extensions: normalizedExtensions,
+      rawRef
+    }),
+    createConversationEvent({
+      kind: `${kindPrefix}_delta`,
+      provider,
+      sessionId,
+      timestamp,
+      payload: { messageId: id, text },
+      extensions: normalizedExtensions,
+      rawRef
+    }),
+    createConversationEvent({
+      kind: `${kindPrefix}_end`,
+      provider,
+      sessionId,
+      timestamp,
+      payload: { messageId: id },
+      extensions: normalizedExtensions,
+      rawRef
+    })
+  ];
+}
+
+function createTextDeltaEvents({
+  kindPrefix = 'assistant_text',
+  text,
+  provider,
+  sessionId,
+  timestamp,
+  messageId,
+  extensions = {},
+  rawRef = null
+}) {
+  if (typeof text !== 'string' || !text) return [];
+  const id = messageId || createEventId(kindPrefix);
+  const normalizedExtensions = { ...extensions, messageId: id };
+
+  return [
+    createConversationEvent({
+      kind: `${kindPrefix}_start`,
+      provider,
+      sessionId,
+      timestamp,
+      payload: { messageId: id },
+      extensions: normalizedExtensions,
+      rawRef
+    }),
+    createConversationEvent({
+      kind: `${kindPrefix}_delta`,
+      provider,
+      sessionId,
+      timestamp,
+      payload: { messageId: id, text },
+      extensions: normalizedExtensions,
+      rawRef
+    })
+  ];
+}
+
+function createTextEndEvent({
+  kindPrefix = 'assistant_text',
+  provider,
+  sessionId,
+  timestamp,
+  messageId,
+  extensions = {},
+  rawRef = null
+}) {
+  if (!messageId) return [];
+  return [
+    createConversationEvent({
+      kind: `${kindPrefix}_end`,
+      provider,
+      sessionId,
+      timestamp,
+      payload: { messageId },
+      extensions: { ...extensions, messageId },
+      rawRef
+    })
+  ];
+}
+
+function isHiddenSystemContextContent(value) {
+  const text = String(value || '').trim();
+  if (!text) return true;
+  return text.startsWith('[System Context]') || text.startsWith('[Attached Context]') || text.startsWith('[Dynamic Context]') || text.startsWith('[Hidden Context]');
+}
+
+function stringifyToolContent(value) {
+  if (typeof value === 'string') return value;
+  if (value == null) return '';
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+function collectClaudeToolResults(rawMessages) {
+  const toolResults = new Map();
+  for (const msg of rawMessages || []) {
+    if (msg?.message?.role !== 'user' || !Array.isArray(msg?.message?.content)) continue;
+    for (const part of msg.message.content) {
+      if (part?.type === 'tool_result' && part.tool_use_id) {
+        toolResults.set(part.tool_use_id, {
+          content: part.content,
+          isError: !!part.is_error,
+          timestamp: msg.timestamp,
+          toolUseResult: msg.toolUseResult || null
+        });
+      }
+    }
+  }
+  return toolResults;
+}
+
+function findLatestTimelineMessageIndex(messages, predicate) {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    if (predicate(messages[index], index)) {
+      return index;
+    }
+  }
+  return -1;
+}
+
+function appendDeltaText(existing = '', delta = '') {
+  if (!delta) return existing;
+  if (!existing) return delta;
+  if (existing.endsWith(delta)) return existing;
+  return `${existing}${delta}`;
+}
+
+function ensureStreamingTextMessage(messages, {
+  messageId,
+  timestamp,
+  provider,
+  isThinking = false,
+  kind = 'assistant'
+}) {
+  const index = findLatestTimelineMessageIndex(messages, (message) => (
+    message?.eventMessageId === messageId &&
+    !!message?.isStreaming &&
+    !message.isToolUse &&
+    !!message.isThinking === !!isThinking
+  ));
+
+  if (index >= 0) {
+    const existing = { ...messages[index] };
+    existing.isStreaming = true;
+    if (provider) existing.provider = provider;
+    if (timestamp) existing.timestamp = existing.timestamp || timestamp;
+    messages[index] = existing;
+    return { messages, index };
+  }
+
+  const nextMessage = {
+    type: kind,
+    content: '',
+    timestamp,
+    provider,
+    isStreaming: true,
+    eventMessageId: messageId
+  };
+
+  if (isThinking) {
+    nextMessage.isThinking = true;
+  }
+
+  messages.push(nextMessage);
+  return { messages, index: messages.length - 1 };
+}
+
+function ensureToolMessage(messages, {
+  toolCallId,
+  toolName,
+  timestamp,
+  provider
+}) {
+  const index = findLatestTimelineMessageIndex(messages, (message) => (
+    message?.isToolUse &&
+    (message.toolId === toolCallId || message.toolCallId === toolCallId)
+  ));
+
+  if (index >= 0) {
+    const existing = { ...messages[index] };
+    if (toolName) existing.toolName = toolName;
+    if (provider) existing.provider = provider;
+    if (timestamp && !existing.timestamp) existing.timestamp = timestamp;
+    messages[index] = existing;
+    return { messages, index };
+  }
+
+  messages.push({
+    type: 'assistant',
+    content: '',
+    timestamp,
+    provider,
+    isToolUse: true,
+    toolName: toolName || 'Unknown Tool',
+    toolId: toolCallId,
+    toolCallId
+  });
+
+  return { messages, index: messages.length - 1 };
+}
+
+export function normalizeLegacyHistoryEntries(rawMessages = [], provider = 'claude', sessionId = null) {
+  if (!Array.isArray(rawMessages)) return [];
+
+  const events = [];
+  const toolResults = collectClaudeToolResults(rawMessages);
+
+  for (const msg of rawMessages) {
+    const timestamp = normalizeTimestamp(msg?.timestamp);
+    const rawRef = { provider, timestamp, type: msg?.type || msg?.message?.role || 'unknown' };
+
+    if (msg?.message?.role === 'user' && msg?.message?.content) {
+      let content = '';
+      if (Array.isArray(msg.message.content)) {
+        content = msg.message.content.filter((part) => part?.type === 'text').map((part) => part?.text || '').join('\n');
+      } else {
+        content = typeof msg.message.content === 'string' ? msg.message.content : String(msg.message.content || '');
+      }
+
+      if (!isHiddenSystemContextContent(content)) {
+        events.push(createConversationEvent({
+          kind: CONVERSATION_EVENT_KINDS.USER_MESSAGE,
+          provider,
+          sessionId,
+          timestamp,
+          payload: { text: content },
+          rawRef
+        }));
+      }
+      continue;
+    }
+
+    if (msg?.type === 'thinking' && msg?.message?.content) {
+      events.push(...createTextSpanEvents({ kindPrefix: 'reasoning', text: msg.message.content, provider, sessionId, timestamp, rawRef }));
+      continue;
+    }
+
+    if (msg?.type === 'tool_use' && msg?.toolName) {
+      const toolCallId = msg.toolCallId || createEventId('tool');
+      const result = msg.toolResult || null;
+      events.push(createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.TOOL_CALL_START, provider, sessionId, timestamp, payload: { toolCallId, toolName: msg.toolName }, rawRef }));
+      events.push(createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.TOOL_CALL_INPUT, provider, sessionId, timestamp, payload: { toolCallId, input: msg.toolInput || '' }, rawRef }));
+      events.push(createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.TOOL_CALL_END, provider, sessionId, timestamp, payload: { toolCallId, toolName: msg.toolName }, rawRef }));
+      if (result) {
+        events.push(createConversationEvent({
+          kind: CONVERSATION_EVENT_KINDS.TOOL_RESULT,
+          provider,
+          sessionId,
+          timestamp: result.timestamp || timestamp,
+          payload: { toolCallId, content: stringifyToolContent(result.content), isError: !!result.isError, toolUseResult: result.toolUseResult || null },
+          rawRef
+        }));
+      }
+      continue;
+    }
+
+    if (msg?.type === 'tool_result') {
+      events.push(createConversationEvent({
+        kind: CONVERSATION_EVENT_KINDS.TOOL_RESULT,
+        provider,
+        sessionId,
+        timestamp,
+        payload: { toolCallId: msg.toolCallId || null, content: stringifyToolContent(msg.output || ''), isError: false },
+        rawRef
+      }));
+      continue;
+    }
+
+    if (msg?.message?.role === 'assistant' && msg?.message?.content) {
+      if (Array.isArray(msg.message.content)) {
+        for (const part of msg.message.content) {
+          if (part?.type === 'text' && !isHiddenSystemContextContent(part.text)) {
+            events.push(...createTextSpanEvents({ text: part.text, provider, sessionId, timestamp, rawRef }));
+          } else if (part?.type === 'tool_use') {
+            const toolCallId = part.id || createEventId('tool');
+            const result = toolResults.get(part.id);
+            events.push(createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.TOOL_CALL_START, provider, sessionId, timestamp, payload: { toolCallId, toolName: part.name }, rawRef }));
+            events.push(createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.TOOL_CALL_INPUT, provider, sessionId, timestamp, payload: { toolCallId, input: stringifyToolContent(part.input || {}) }, rawRef }));
+            events.push(createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.TOOL_CALL_END, provider, sessionId, timestamp, payload: { toolCallId, toolName: part.name }, rawRef }));
+            if (result) {
+              events.push(createConversationEvent({
+                kind: CONVERSATION_EVENT_KINDS.TOOL_RESULT,
+                provider,
+                sessionId,
+                timestamp: result.timestamp || timestamp,
+                payload: { toolCallId, content: stringifyToolContent(result.content), isError: !!result.isError, toolUseResult: result.toolUseResult || null },
+                rawRef
+              }));
+            }
+          }
+        }
+      } else if (!isHiddenSystemContextContent(msg.message.content)) {
+        events.push(...createTextSpanEvents({ text: msg.message.content, provider, sessionId, timestamp, rawRef }));
+      }
+      continue;
+    }
+
+    if (msg?.type && /error/i.test(msg.type)) {
+      events.push(createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.ERROR, provider, sessionId, timestamp, payload: { message: msg.error || msg.message || 'Provider error' }, rawRef }));
+    }
+  }
+
+  return events.sort((a, b) => new Date(a.timestamp) - new Date(b.timestamp));
+}
+
+export function applyConversationEventToTimelineMessages(messages = [], event, sessionProvider = 'claude') {
+  const nextMessages = Array.isArray(messages) ? [...messages] : [];
+  if (!isConversationEvent(event)) return nextMessages;
+
+  const provider = event.provider || sessionProvider;
+  const timestamp = event.timestamp || new Date().toISOString();
+  const payload = event.payload || {};
+
+  switch (event.kind) {
+    case CONVERSATION_EVENT_KINDS.USER_MESSAGE:
+      nextMessages.push({
+        type: 'user',
+        content: payload.text || '',
+        timestamp,
+        provider
+      });
+      break;
+
+    case CONVERSATION_EVENT_KINDS.ASSISTANT_TEXT_START: {
+      const messageId = payload.messageId || event.extensions?.messageId || createEventId('assistant_text');
+      ensureStreamingTextMessage(nextMessages, { messageId, timestamp, provider, isThinking: false });
+      break;
+    }
+
+    case CONVERSATION_EVENT_KINDS.ASSISTANT_TEXT_DELTA: {
+      const messageId = payload.messageId || event.extensions?.messageId || createEventId('assistant_text');
+      const { index } = ensureStreamingTextMessage(nextMessages, { messageId, timestamp, provider, isThinking: false });
+      const target = { ...nextMessages[index] };
+      target.content = appendDeltaText(target.content || '', payload.text || '');
+      target.timestamp = target.timestamp || timestamp;
+      target.provider = target.provider || provider;
+      nextMessages[index] = target;
+      break;
+    }
+
+    case CONVERSATION_EVENT_KINDS.ASSISTANT_TEXT_END: {
+      const messageId = payload.messageId || event.extensions?.messageId;
+      if (!messageId) break;
+      const index = findLatestTimelineMessageIndex(nextMessages, (message) => (
+        message?.eventMessageId === messageId && !message.isToolUse && !message.isThinking
+      ));
+      if (index >= 0) {
+        nextMessages[index] = { ...nextMessages[index], isStreaming: false };
+      }
+      break;
+    }
+
+    case CONVERSATION_EVENT_KINDS.REASONING_START: {
+      const messageId = payload.messageId || event.extensions?.messageId || createEventId('reasoning');
+      ensureStreamingTextMessage(nextMessages, { messageId, timestamp, provider, isThinking: true });
+      break;
+    }
+
+    case CONVERSATION_EVENT_KINDS.REASONING_DELTA: {
+      const messageId = payload.messageId || event.extensions?.messageId || createEventId('reasoning');
+      const { index } = ensureStreamingTextMessage(nextMessages, { messageId, timestamp, provider, isThinking: true });
+      const target = { ...nextMessages[index] };
+      target.content = appendDeltaText(target.content || '', payload.text || '');
+      target.timestamp = target.timestamp || timestamp;
+      target.provider = target.provider || provider;
+      target.isThinking = true;
+      nextMessages[index] = target;
+      break;
+    }
+
+    case CONVERSATION_EVENT_KINDS.REASONING_END: {
+      const messageId = payload.messageId || event.extensions?.messageId;
+      if (!messageId) break;
+      const index = findLatestTimelineMessageIndex(nextMessages, (message) => (
+        message?.eventMessageId === messageId && !!message.isThinking
+      ));
+      if (index >= 0) {
+        nextMessages[index] = { ...nextMessages[index], isStreaming: false, isThinking: true };
+      }
+      break;
+    }
+
+    case CONVERSATION_EVENT_KINDS.TOOL_CALL_START: {
+      const toolCallId = payload.toolCallId || createEventId('tool');
+      const { index } = ensureToolMessage(nextMessages, {
+        toolCallId,
+        toolName: payload.toolName,
+        timestamp,
+        provider
+      });
+      nextMessages[index] = { ...nextMessages[index], toolName: payload.toolName || nextMessages[index].toolName };
+      break;
+    }
+
+    case CONVERSATION_EVENT_KINDS.TOOL_CALL_INPUT: {
+      const toolCallId = payload.toolCallId || createEventId('tool');
+      const { index } = ensureToolMessage(nextMessages, {
+        toolCallId,
+        toolName: payload.toolName,
+        timestamp,
+        provider
+      });
+      nextMessages[index] = {
+        ...nextMessages[index],
+        toolInput: stringifyToolContent(payload.input || ''),
+        provider: nextMessages[index].provider || provider
+      };
+      break;
+    }
+
+    case CONVERSATION_EVENT_KINDS.TOOL_CALL_END: {
+      const toolCallId = payload.toolCallId || event.extensions?.toolCallId;
+      if (!toolCallId) break;
+      const { index } = ensureToolMessage(nextMessages, {
+        toolCallId,
+        toolName: payload.toolName,
+        timestamp,
+        provider
+      });
+      nextMessages[index] = { ...nextMessages[index], toolName: payload.toolName || nextMessages[index].toolName };
+      break;
+    }
+
+    case CONVERSATION_EVENT_KINDS.TOOL_RESULT: {
+      const toolCallId = payload.toolCallId || event.extensions?.toolCallId || createEventId('tool');
+      const { index } = ensureToolMessage(nextMessages, {
+        toolCallId,
+        toolName: payload.toolName,
+        timestamp,
+        provider
+      });
+      nextMessages[index] = {
+        ...nextMessages[index],
+        toolResult: {
+          content: stringifyToolContent(payload.content || ''),
+          isError: !!payload.isError,
+          toolUseResult: payload.toolUseResult || null,
+          timestamp
+        },
+        toolError: !!payload.isError,
+        provider: nextMessages[index].provider || provider
+      };
+      break;
+    }
+
+    case CONVERSATION_EVENT_KINDS.APPROVAL_REQUEST:
+      if (payload.message) {
+        nextMessages.push({
+          type: 'assistant',
+          content: payload.message,
+          timestamp,
+          provider,
+          isApprovalRequest: true,
+          approvalRequest: payload
+        });
+      }
+      break;
+
+    case CONVERSATION_EVENT_KINDS.APPROVAL_RESOLVED:
+      if (payload.message) {
+        nextMessages.push({
+          type: 'assistant',
+          content: payload.message,
+          timestamp,
+          provider,
+          approvalResolution: payload
+        });
+      }
+      break;
+
+    case CONVERSATION_EVENT_KINDS.SYSTEM_NOTICE:
+      if (payload.message) {
+        const last = nextMessages[nextMessages.length - 1];
+        if (!(last && last.type === 'assistant' && !last.isToolUse && (last.content || '').trim() === String(payload.message).trim())) {
+          nextMessages.push({
+            type: 'assistant',
+            content: payload.message,
+            timestamp,
+            provider,
+            isSystemNotice: true
+          });
+        }
+      }
+      break;
+
+    case CONVERSATION_EVENT_KINDS.ERROR:
+      nextMessages.push({
+        type: 'error',
+        content: payload.message || 'Provider error',
+        timestamp,
+        provider,
+        rawRef: event.rawRef || null,
+        extensions: event.extensions || {}
+      });
+      break;
+
+    case CONVERSATION_EVENT_KINDS.SESSION_STATE_CHANGED:
+    case CONVERSATION_EVENT_KINDS.ARTIFACT_CREATED:
+    default:
+      break;
+  }
+
+  return nextMessages;
+}
+
+export function conversationEventsToTimelineMessages(events = [], sessionProvider = 'claude') {
+  if (!Array.isArray(events)) return [];
+  if (events.length > 0 && !isConversationEvent(events[0])) {
+    return conversationEventsToTimelineMessages(normalizeLegacyHistoryEntries(events, sessionProvider), sessionProvider);
+  }
+
+  return events.reduce(
+    (messages, event) => applyConversationEventToTimelineMessages(messages, event, sessionProvider),
+    []
+  );
+}
+
+function inferRealtimeMessageId(payload, provider, sessionId, kindPrefix = 'assistant_text') {
+  const data = payload?.data || {};
+  const idCandidate =
+    data.itemId ||
+    data.messageId ||
+    data.id ||
+    data.contentBlockId ||
+    data.blockId ||
+    (data.index !== undefined ? `${kindPrefix}:${data.index}` : null) ||
+    `${kindPrefix}:main`;
+
+  return `${provider}:${sessionId || 'pending'}:${idCandidate}`;
+}
+
+function mapCodexStructuredItemToEvents({ provider, sessionId, timestamp, data, rawRef }) {
+  const toolCallId = `${provider}:${sessionId || 'pending'}:${data.itemType || 'item'}:${timestamp}`;
+
+  switch (data.itemType) {
+    case 'command_execution':
+      return [
+        createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.TOOL_CALL_START, provider, sessionId, timestamp, payload: { toolCallId, toolName: 'Bash' }, rawRef }),
+        createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.TOOL_CALL_INPUT, provider, sessionId, timestamp, payload: { toolCallId, input: data.command || '' }, rawRef }),
+        createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.TOOL_CALL_END, provider, sessionId, timestamp, payload: { toolCallId, toolName: 'Bash' }, rawRef }),
+        createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.TOOL_RESULT, provider, sessionId, timestamp, payload: { toolCallId, content: data.output || `Exit code: ${data.exitCode ?? 'unknown'}`, isError: data.status === 'failed' || Number(data.exitCode) > 0 }, rawRef })
+      ];
+
+    case 'file_change':
+      return [
+        createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.TOOL_CALL_START, provider, sessionId, timestamp, payload: { toolCallId, toolName: 'FileChanges' }, rawRef }),
+        createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.TOOL_CALL_INPUT, provider, sessionId, timestamp, payload: { toolCallId, input: data.changes || [] }, rawRef }),
+        createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.TOOL_CALL_END, provider, sessionId, timestamp, payload: { toolCallId, toolName: 'FileChanges' }, rawRef }),
+        createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.TOOL_RESULT, provider, sessionId, timestamp, payload: { toolCallId, content: `Status: ${data.status || 'completed'}`, isError: false }, rawRef })
+      ];
+
+    case 'mcp_tool_call':
+      return [
+        createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.TOOL_CALL_START, provider, sessionId, timestamp, payload: { toolCallId, toolName: `${data.server}:${data.tool}` }, rawRef }),
+        createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.TOOL_CALL_INPUT, provider, sessionId, timestamp, payload: { toolCallId, input: data.arguments || {} }, rawRef }),
+        createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.TOOL_CALL_END, provider, sessionId, timestamp, payload: { toolCallId, toolName: `${data.server}:${data.tool}` }, rawRef }),
+        createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.TOOL_RESULT, provider, sessionId, timestamp, payload: { toolCallId, content: data.result || data.error?.message || '', isError: !!data.error }, rawRef })
+      ];
+
+    case 'web_search':
+      return [
+        createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.TOOL_CALL_START, provider, sessionId, timestamp, payload: { toolCallId, toolName: 'WebSearch' }, rawRef }),
+        createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.TOOL_CALL_INPUT, provider, sessionId, timestamp, payload: { toolCallId, input: data.query || '' }, rawRef }),
+        createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.TOOL_CALL_END, provider, sessionId, timestamp, payload: { toolCallId, toolName: 'WebSearch' }, rawRef })
+      ];
+
+    case 'todo_list':
+      return [
+        createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.TOOL_CALL_START, provider, sessionId, timestamp, payload: { toolCallId, toolName: 'TodoList' }, rawRef }),
+        createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.TOOL_CALL_INPUT, provider, sessionId, timestamp, payload: { toolCallId, input: data.items || [] }, rawRef }),
+        createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.TOOL_CALL_END, provider, sessionId, timestamp, payload: { toolCallId, toolName: 'TodoList' }, rawRef })
+      ];
+
+    case 'error':
+      return [
+        createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.ERROR, provider, sessionId, timestamp, payload: { message: data.message?.content || 'Codex error' }, rawRef })
+      ];
+
+    default:
+      return [];
+  }
+}
+
+export function normalizeRealtimePayloadToConversationEvents(payload, fallbackProvider = 'claude') {
+  if (!payload || typeof payload !== 'object') return [];
+
+  const provider = payload.provider || (String(payload.type || '').startsWith('codex') ? 'codex' : fallbackProvider);
+  const sessionId = payload.sessionId || null;
+  const timestamp = normalizeTimestamp(payload.timestamp);
+  const rawRef = { type: payload.type };
+
+  if (payload.type === 'session-created') {
+    return [
+      createConversationEvent({
+        kind: CONVERSATION_EVENT_KINDS.SESSION_STATE_CHANGED,
+        provider,
+        sessionId,
+        timestamp,
+        payload: { state: 'queued', created: true },
+        rawRef
+      })
+    ];
+  }
+
+  if (payload.type === 'claude-permission-request') {
+    return [
+      createConversationEvent({
+        kind: CONVERSATION_EVENT_KINDS.APPROVAL_REQUEST,
+        provider,
+        sessionId,
+        timestamp,
+        payload: {
+          requestId: payload.requestId || null,
+          toolName: payload.toolName,
+          input: payload.input ?? payload.toolInput,
+          context: payload.context || null,
+          sessionId,
+          message: payload.message || `Approval required for ${payload.toolName || 'tool execution'}`
+        },
+        extensions: {
+          requestId: payload.requestId || null
+        },
+        rawRef
+      })
+    ];
+  }
+
+  if (payload.type === 'claude-permission-cancelled') {
+    return [
+      createConversationEvent({
+        kind: CONVERSATION_EVENT_KINDS.APPROVAL_RESOLVED,
+        provider,
+        sessionId,
+        timestamp,
+        payload: {
+          requestId: payload.requestId || null,
+          status: 'cancelled',
+          reason: payload.reason || null,
+          message: payload.message || 'Approval request cancelled'
+        },
+        extensions: {
+          requestId: payload.requestId || null
+        },
+        rawRef
+      })
+    ];
+  }
+
+  if (payload.type === 'claude-permission-resolved') {
+    return [
+      createConversationEvent({
+        kind: CONVERSATION_EVENT_KINDS.APPROVAL_RESOLVED,
+        provider,
+        sessionId,
+        timestamp,
+        payload: {
+          requestId: payload.requestId || null,
+          status: payload.status || 'resolved',
+          toolName: payload.toolName || null,
+          message: payload.message || null
+        },
+        extensions: {
+          requestId: payload.requestId || null
+        },
+        rawRef
+      })
+    ];
+  }
+
+  if (payload.type === 'session-aborted') {
+    return [
+      createConversationEvent({
+        kind: CONVERSATION_EVENT_KINDS.SESSION_STATE_CHANGED,
+        provider,
+        sessionId,
+        timestamp,
+        payload: {
+          state: 'aborted',
+          success: payload.success !== false
+        },
+        rawRef
+      })
+    ];
+  }
+
+  if (payload.type === 'session-status') {
+    return [
+      createConversationEvent({
+        kind: CONVERSATION_EVENT_KINDS.SESSION_STATE_CHANGED,
+        provider,
+        sessionId,
+        timestamp,
+        payload: {
+          state: payload.isProcessing ? 'streaming' : 'idle'
+        },
+        rawRef
+      })
+    ];
+  }
+
+  if (payload.type === 'claude-response') {
+    const data = payload.data || {};
+
+    if (data.type === 'content_block_delta' && typeof data.delta?.text === 'string') {
+      const isReasoning = !!data.isReasoning || data.itemType === 'reasoning' || data.delta?.type === 'thinking_delta';
+      const kindPrefix = isReasoning ? 'reasoning' : 'assistant_text';
+      return createTextDeltaEvents({
+        kindPrefix,
+        text: data.delta.text,
+        provider,
+        sessionId,
+        timestamp,
+        messageId: inferRealtimeMessageId(payload, provider, sessionId, kindPrefix),
+        rawRef
+      });
+    }
+
+    if (data.type === 'content_block_stop') {
+      const isReasoning = !!data.isReasoning || data.itemType === 'reasoning';
+      const kindPrefix = isReasoning ? 'reasoning' : 'assistant_text';
+      return createTextEndEvent({
+        kindPrefix,
+        provider,
+        sessionId,
+        timestamp,
+        messageId: inferRealtimeMessageId(payload, provider, sessionId, kindPrefix),
+        rawRef
+      });
+    }
+
+    if (data.type === 'thinking' && data.message?.content) {
+      return createTextSpanEvents({
+        kindPrefix: 'reasoning',
+        text: data.message.content,
+        provider,
+        sessionId,
+        timestamp,
+        rawRef
+      });
+    }
+
+    if (Array.isArray(data.content)) {
+      return data.content.flatMap((part) => {
+        if (part?.type === 'text' && !isHiddenSystemContextContent(part.text)) {
+          return createTextSpanEvents({
+            text: part.text,
+            provider,
+            sessionId,
+            timestamp,
+            messageId: part.id ? `${provider}:${sessionId || 'pending'}:${part.id}` : undefined,
+            rawRef
+          });
+        }
+
+        if (part?.type === 'tool_use') {
+          const toolCallId = part.id || createEventId('tool');
+          return [
+            createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.TOOL_CALL_START, provider, sessionId, timestamp, payload: { toolCallId, toolName: part.name }, rawRef }),
+            createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.TOOL_CALL_INPUT, provider, sessionId, timestamp, payload: { toolCallId, input: part.input || {} }, rawRef }),
+            createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.TOOL_CALL_END, provider, sessionId, timestamp, payload: { toolCallId, toolName: part.name }, rawRef })
+          ];
+        }
+
+        return [];
+      });
+    }
+
+    if (data.role === 'user' && Array.isArray(data.content)) {
+      return data.content.flatMap((part) => (
+        part?.type === 'tool_result'
+          ? [createConversationEvent({
+              kind: CONVERSATION_EVENT_KINDS.TOOL_RESULT,
+              provider,
+              sessionId,
+              timestamp,
+              payload: {
+                toolCallId: part.tool_use_id || createEventId('tool'),
+                content: part.content,
+                isError: !!part.is_error
+              },
+              rawRef
+            })]
+          : []
+      ));
+    }
+
+    if (typeof data.content === 'string' && data.content.trim() && !isHiddenSystemContextContent(data.content)) {
+      return createTextSpanEvents({ text: data.content, provider, sessionId, timestamp, rawRef });
+    }
+
+    return [];
+  }
+
+  if (payload.type === 'claude-output') {
+    const content = String(payload.data || '').trim();
+    if (!content) return [];
+    return [
+      createConversationEvent({
+        kind: CONVERSATION_EVENT_KINDS.SYSTEM_NOTICE,
+        provider,
+        sessionId,
+        timestamp,
+        payload: { message: content },
+        rawRef
+      })
+    ];
+  }
+
+  if (payload.type === 'codex-response') {
+    const data = payload.data || {};
+
+    if (data.type === 'provider_notice' && typeof data.message === 'string' && data.message.trim()) {
+      return [
+        createConversationEvent({
+          kind: CONVERSATION_EVENT_KINDS.SYSTEM_NOTICE,
+          provider: payload.provider || 'codex',
+          sessionId,
+          timestamp,
+          payload: { message: data.message.trim() },
+          rawRef
+        })
+      ];
+    }
+
+    if (data.type === 'item_delta' && typeof data.delta === 'string') {
+      const kindPrefix = (data.isReasoning || data.itemType === 'reasoning') ? 'reasoning' : 'assistant_text';
+      return createTextDeltaEvents({
+        kindPrefix,
+        text: data.delta,
+        provider: payload.provider || 'codex',
+        sessionId,
+        timestamp,
+        messageId: data.itemId ? `${provider}:${sessionId || 'pending'}:${data.itemId}` : inferRealtimeMessageId(payload, provider, sessionId, kindPrefix),
+        rawRef
+      });
+    }
+
+    if (data.type === 'item_done') {
+      const kindPrefix = (data.isReasoning || data.itemType === 'reasoning') ? 'reasoning' : 'assistant_text';
+      return createTextEndEvent({
+        kindPrefix,
+        provider: payload.provider || 'codex',
+        sessionId,
+        timestamp,
+        messageId: data.itemId ? `${provider}:${sessionId || 'pending'}:${data.itemId}` : inferRealtimeMessageId(payload, provider, sessionId, kindPrefix),
+        rawRef
+      });
+    }
+
+    if (data.type === 'item') {
+      return mapCodexStructuredItemToEvents({ provider: payload.provider || 'codex', sessionId, timestamp, data, rawRef });
+    }
+
+    if (data.type === 'turn_complete') {
+      return [
+        createConversationEvent({
+          kind: CONVERSATION_EVENT_KINDS.SESSION_STATE_CHANGED,
+          provider: payload.provider || 'codex',
+          sessionId,
+          timestamp,
+          payload: { state: 'completed' },
+          rawRef
+        })
+      ];
+    }
+
+    if (data.type === 'turn_failed') {
+      return [
+        createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.ERROR, provider: payload.provider || 'codex', sessionId, timestamp, payload: { message: data.error?.message || 'Codex turn failed' }, rawRef }),
+        createConversationEvent({ kind: CONVERSATION_EVENT_KINDS.SESSION_STATE_CHANGED, provider: payload.provider || 'codex', sessionId, timestamp, payload: { state: 'errored' }, rawRef })
+      ];
+    }
+
+    return [];
+  }
+
+  if (payload.type === 'gemini-result') {
+    return [
+      createConversationEvent({
+        kind: CONVERSATION_EVENT_KINDS.SESSION_STATE_CHANGED,
+        provider,
+        sessionId,
+        timestamp,
+        payload: { state: 'completed' },
+        rawRef
+      })
+    ];
+  }
+
+  if (payload.type === 'claude-complete' || payload.type === 'codex-complete') {
+    return [
+      createConversationEvent({
+        kind: CONVERSATION_EVENT_KINDS.SESSION_STATE_CHANGED,
+        provider,
+        sessionId,
+        timestamp,
+        payload: { state: 'completed', exitCode: payload.exitCode ?? 0 },
+        rawRef
+      })
+    ];
+  }
+
+  if (/error/i.test(payload.type || '')) {
+    return [
+      createConversationEvent({
+        kind: CONVERSATION_EVENT_KINDS.ERROR,
+        provider,
+        sessionId,
+        timestamp,
+        payload: { message: payload.error || 'Provider error' },
+        rawRef
+      }),
+      createConversationEvent({
+        kind: CONVERSATION_EVENT_KINDS.SESSION_STATE_CHANGED,
+        provider,
+        sessionId,
+        timestamp,
+        payload: { state: 'errored' },
+        rawRef
+      })
+    ];
+  }
+
+  return [];
+}