wind-agent-cli 1.37.2 → 1.38.0

package/server/modules/providers/list/codex/codex-sessions.provider.ts

@@ -1,938 +1,938 @@
-import fsSync from 'node:fs';
-import readline from 'node:readline';
-
-import { sessionsDb } from '@/modules/database/index.js';
-import { parseFilesInputTag, toImageAttachments } from '@/shared/image-attachments.js';
-import type { IProviderSessions } from '@/shared/interfaces.js';
-import type { AnyRecord, FetchHistoryOptions, FetchHistoryResult, NormalizedMessage } from '@/shared/types.js';
-import { createNormalizedMessage, generateMessageId, readObjectRecord, sliceTailPage } from '@/shared/utils.js';
-
-const PROVIDER = 'codex';
-
-type CodexHistoryResult =
-  | AnyRecord[]
-  | {
-      messages?: AnyRecord[];
-      total?: number;
-      hasMore?: boolean;
-      offset?: number;
-      limit?: number | null;
-      tokenUsage?: unknown;
-    };
-
-function isVisibleCodexUserMessage(payload: AnyRecord | null | undefined): boolean {
-  if (!payload || payload.type !== 'user_message') {
-    return false;
-  }
-
-  if (payload.kind && payload.kind !== 'plain') {
-    return false;
-  }
-
-  return typeof payload.message === 'string' && payload.message.trim().length > 0;
-}
-
-/**
- * Reads the image attachments Codex records on `user_message` events.
- * Turns sent with `local_image` input items land in `local_images` as file
- * paths (verified against real rollout JSONL); the `images` array can carry
- * base64 data URLs, which are passed through as inline `data` attachments so
- * the UI can preview them without a file lookup.
- *
- * Exported for tests.
- */
-export function extractCodexUserImages(
-  payload: AnyRecord | null | undefined,
-): Array<{ path?: string; data?: string }> | undefined {
-  if (!payload) {
-    return undefined;
-  }
-
-  const candidates = [
-    ...(Array.isArray(payload.local_images) ? payload.local_images : []),
-    ...(Array.isArray(payload.images) ? payload.images : []),
-  ];
-
-  const attachments: Array<{ path?: string; data?: string }> = [];
-  for (const entry of candidates) {
-    if (typeof entry !== 'string' || !entry.trim()) {
-      continue;
-    }
-    if (entry.startsWith('data:')) {
-      attachments.push({ data: entry });
-    } else {
-      attachments.push(...toImageAttachments([entry]));
-    }
-  }
-
-  return attachments.length > 0 ? attachments : undefined;
-}
-
-function extractCodexTextContent(content: unknown): string {
-  if (!Array.isArray(content)) {
-    return typeof content === 'string' ? content : '';
-  }
-
-  return content
-    .map((item) => {
-      if (!item || typeof item !== 'object') {
-        return '';
-      }
-
-      const record = item as AnyRecord;
-      if (
-        (record.type === 'input_text' || record.type === 'output_text' || record.type === 'text')
-        && typeof record.text === 'string'
-      ) {
-        return record.text;
-      }
-
-      return '';
-    })
-    .filter(Boolean)
-    .join('\n');
-}
-
-function extractCodexToolOutput(output: unknown): string {
-  if (typeof output === 'string') {
-    return output;
-  }
-
-  if (!Array.isArray(output)) {
-    return output == null ? '' : JSON.stringify(output);
-  }
-
-  return output
-    .map((item) => {
-      const record = readObjectRecord(item);
-      return typeof record?.text === 'string' ? record.text : '';
-    })
-    .filter(Boolean)
-    .join('');
-}
-
-function readRunningExecOutput(output: string): { cellId: string; content: string } | null {
-  const runningCell = /Script running with cell ID\s+(\S+)/i.exec(output);
-  if (!runningCell) {
-    return null;
-  }
-
-  const outputMarker = /\r?\nOutput:\r?\n/i.exec(output);
-  return {
-    cellId: runningCell[1],
-    content: outputMarker ? output.slice((outputMarker.index || 0) + outputMarker[0].length) : '',
-  };
-}
-
-function decodeJavaScriptStringLiteral(literal: string): string {
-  if (literal.startsWith('"')) {
-    try {
-      return JSON.parse(literal) as string;
-    } catch {
-      return literal.slice(1, -1);
-    }
-  }
-
-  return literal
-    .slice(1, -1)
-    .replace(/\\n/g, '\n')
-    .replace(/\\r/g, '\r')
-    .replace(/\\t/g, '\t')
-    .replace(/\\([\\'`])/g, '$1');
-}
-
-function extractNestedCodexCommands(source: string): string[] {
-  const commands: string[] = [];
-  const commandPattern = /(?:["']command["']|\bcommand)\s*:\s*("(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|`(?:\\.|[^`\\])*`)/gs;
-  for (const match of source.matchAll(commandPattern)) {
-    commands.push(decodeJavaScriptStringLiteral(match[1]));
-  }
-
-  if (commands.length === 0) {
-    const arrayPattern = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*\[([\s\S]*?)\]\s*;/g;
-    const stringPattern = /("(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|`(?:\\.|[^`\\])*`)/g;
-
-    for (const arrayMatch of source.matchAll(arrayPattern)) {
-      const arrayName = arrayMatch[1];
-      if (!new RegExp(`\\b${arrayName}\\.map\\s*\\(`).test(source)) {
-        continue;
-      }
-      for (const stringMatch of arrayMatch[2].matchAll(stringPattern)) {
-        commands.push(decodeJavaScriptStringLiteral(stringMatch[1]));
-      }
-    }
-  }
-
-  return commands;
-}
-
-/**
- * Newer Codex rollouts persist the orchestration wrapper (`exec`) instead of
- * the nested tool name. Recover the useful UI-level operation so history does
- * not degrade into rows labelled only "exec / Parameters".
- */
-function translateCodexExecInput(input: unknown): { toolName: string; toolInput: string } | null {
-  const source = typeof input === 'string' ? input : String(input || '');
-  if (/\btools\.(?:shell_command|exec_command)\s*\(/.test(source)) {
-    const commands = extractNestedCodexCommands(source);
-    if (commands.length > 0) {
-      return {
-        toolName: 'Bash',
-        toolInput: JSON.stringify({ command: commands.join('\n') }),
-      };
-    }
-  }
-
-  return null;
-}
-
-function humanizeCodexToolName(toolName: string): string {
-  return toolName
-    .replace(/__/g, ' ')
-    .replace(/_/g, ' ')
-    .replace(/\b\w/g, (character) => character.toUpperCase());
-}
-
-type CodexSubagentRecord = {
-  toolCallId: string;
-  message: AnyRecord;
-  agentPath?: string;
-  isComplete: boolean;
-};
-
-function parseCodexSubagentMessage(payload: AnyRecord): {
-  author: string;
-  messageType: string;
-  result: string;
-} | null {
-  const text = extractCodexTextContent(payload.content);
-  const header = /Message Type:\s*([^\r\n]+)[\s\S]*?Sender:\s*([^\r\n]+)[\s\S]*?Payload:\s*\r?\n([\s\S]*)/i.exec(text);
-  const author = readNonEmptyString(payload.author) || header?.[2]?.trim();
-  if (!author) {
-    return null;
-  }
-
-  return {
-    author,
-    messageType: header?.[1]?.trim().toUpperCase() || 'MESSAGE',
-    result: header?.[3]?.trim() || '',
-  };
-}
-
-const CODEX_COLLABORATION_CONTROL_TOOLS = new Set([
-  'followup_task',
-  'interrupt_agent',
-  'list_agents',
-  'send_message',
-  'wait_agent',
-]);
-
-function readNonEmptyString(value: unknown): string | undefined {
-  return typeof value === 'string' && value.length > 0 ? value : undefined;
-}
-
-async function getCodexSessionMessages(
-  sessionId: string,
-  limit: number | null = null,
-  offset = 0,
-): Promise<CodexHistoryResult> {
-  try {
-    const sessionFilePath = sessionsDb.getSessionById(sessionId)?.jsonl_path;
-
-    if (!sessionFilePath) {
-      console.warn(`Codex session file not found for session ${sessionId}`);
-      return { messages: [], total: 0, hasMore: false };
-    }
-
-    const messages: AnyRecord[] = [];
-    let tokenUsage: AnyRecord | null = null;
-    const ignoredToolCallIds = new Set<string>();
-    const execToolCallIds = new Set<string>();
-    const execCallByCellId = new Map<string, string>();
-    const waitCallToExecCall = new Map<string, string>();
-    const pendingExecOutput = new Map<string, string>();
-    const completedExecCalls = new Set<string>();
-    const subagentsByCallId = new Map<string, CodexSubagentRecord>();
-    const subagentsByPath = new Map<string, CodexSubagentRecord>();
-    const fileStream = fsSync.createReadStream(sessionFilePath);
-    const rl = readline.createInterface({
-      input: fileStream,
-      crlfDelay: Infinity,
-    });
-
-    for await (const line of rl) {
-      if (!line.trim()) {
-        continue;
-      }
-
-      try {
-        const entry = JSON.parse(line) as AnyRecord;
-        if (entry.type === 'event_msg' && entry.payload?.type === 'token_count' && entry.payload?.info) {
-          const info = entry.payload.info as AnyRecord;
-          if (info.total_token_usage) {
-            const usage = info.total_token_usage as AnyRecord;
-            tokenUsage = {
-              used: usage.total_tokens || 0,
-              total: info.model_context_window || 200000,
-            };
-          }
-        }
-
-        if (
-          entry.type === 'event_msg'
-          && entry.payload?.type === 'sub_agent_activity'
-          && entry.payload.kind === 'started'
-        ) {
-          const eventId = readNonEmptyString(entry.payload.event_id);
-          const agentPath = readNonEmptyString(entry.payload.agent_path);
-          const subagent = eventId ? subagentsByCallId.get(eventId) : undefined;
-          if (subagent && agentPath) {
-            subagent.agentPath = agentPath;
-            subagentsByPath.set(agentPath, subagent);
-          }
-        }
-
-        if (entry.type === 'event_msg' && isVisibleCodexUserMessage(entry.payload as AnyRecord)) {
-          messages.push({
-            type: 'user',
-            timestamp: entry.timestamp,
-            message: {
-              role: 'user',
-              content: entry.payload.message,
-            },
-            images: extractCodexUserImages(entry.payload as AnyRecord),
-          });
-        }
-
-        if (
-          entry.type === 'response_item' &&
-          entry.payload?.type === 'message' &&
-          entry.payload.role === 'assistant'
-        ) {
-          const textContent = extractCodexTextContent(entry.payload.content);
-          if (textContent.trim()) {
-            messages.push({
-              type: 'assistant',
-              timestamp: entry.timestamp,
-              message: {
-                role: 'assistant',
-                content: textContent,
-              },
-            });
-          }
-        }
-
-        if (entry.type === 'response_item' && entry.payload?.type === 'reasoning') {
-          const summaryText = Array.isArray(entry.payload.summary)
-            ? entry.payload.summary
-                .map((item: AnyRecord) => item?.text)
-                .filter(Boolean)
-                .join('\n')
-            : '';
-
-          if (summaryText.trim()) {
-            messages.push({
-              type: 'thinking',
-              timestamp: entry.timestamp,
-              message: {
-                role: 'assistant',
-                content: summaryText,
-              },
-            });
-          }
-        }
-
-        if (entry.type === 'response_item' && entry.payload?.type === 'agent_message') {
-          const agentMessage = parseCodexSubagentMessage(entry.payload as AnyRecord);
-          if (agentMessage && agentMessage.messageType === 'FINAL_ANSWER' && agentMessage.result) {
-            let subagent = subagentsByPath.get(agentMessage.author);
-            if (!subagent) {
-              const fallbackCallId = entry.payload.id || generateMessageId('codex-subagent');
-              const taskName = agentMessage.author.split('/').filter(Boolean).pop() || 'agent';
-              const taskMessage: AnyRecord = {
-                uuid: fallbackCallId,
-                type: 'tool_use',
-                timestamp: entry.timestamp,
-                toolName: 'Task',
-                toolInput: JSON.stringify({
-                  subagent_type: 'Codex',
-                  description: humanizeCodexToolName(taskName),
-                }),
-                toolCallId: fallbackCallId,
-              };
-              messages.push(taskMessage);
-              subagent = {
-                toolCallId: fallbackCallId,
-                message: taskMessage,
-                agentPath: agentMessage.author,
-                isComplete: false,
-              };
-              subagentsByCallId.set(fallbackCallId, subagent);
-              subagentsByPath.set(agentMessage.author, subagent);
-            }
-
-            if (!subagent.isComplete) {
-              messages.push({
-                type: 'tool_result',
-                timestamp: entry.timestamp,
-                toolCallId: subagent.toolCallId,
-                output: agentMessage.result,
-              });
-              subagent.isComplete = true;
-            }
-          }
-        }
-
-        if (entry.type === 'response_item' && entry.payload?.type === 'function_call') {
-          let toolName = entry.payload.name;
-          let toolInput = entry.payload.arguments;
-
-          if (toolName === 'spawn_agent') {
-            let taskName = 'agent';
-            try {
-              const args = JSON.parse(String(entry.payload.arguments || '{}')) as AnyRecord;
-              taskName = readNonEmptyString(args.task_name) || taskName;
-            } catch {
-              // The activity event can still provide the canonical agent path.
-            }
-
-            const taskMessage: AnyRecord = {
-              uuid: entry.payload.call_id,
-              type: 'tool_use',
-              timestamp: entry.timestamp,
-              toolName: 'Task',
-              toolInput: JSON.stringify({
-                subagent_type: 'Codex',
-                description: humanizeCodexToolName(taskName),
-              }),
-              toolCallId: entry.payload.call_id,
-            };
-            messages.push(taskMessage);
-            subagentsByCallId.set(entry.payload.call_id, {
-              toolCallId: entry.payload.call_id,
-              message: taskMessage,
-              isComplete: false,
-            });
-            ignoredToolCallIds.add(entry.payload.call_id);
-            continue;
-          }
-
-          if (toolName === 'wait') {
-            try {
-              const args = JSON.parse(String(entry.payload.arguments || '{}')) as AnyRecord;
-              const cellId = String(args.cell_id || '');
-              const execCallId = execCallByCellId.get(cellId);
-              if (execCallId) {
-                waitCallToExecCall.set(entry.payload.call_id, execCallId);
-              }
-            } catch {
-              // Suppress the orchestration wait even when its payload is malformed.
-            }
-            ignoredToolCallIds.add(entry.payload.call_id);
-            continue;
-          }
-
-          if (CODEX_COLLABORATION_CONTROL_TOOLS.has(toolName)) {
-            ignoredToolCallIds.add(entry.payload.call_id);
-            continue;
-          }
-
-          if (toolName === 'shell_command') {
-            toolName = 'Bash';
-            try {
-              const args = JSON.parse(entry.payload.arguments) as AnyRecord;
-              toolInput = JSON.stringify({ command: args.command });
-            } catch {
-              // Keep original arguments when parsing fails.
-            }
-          }
-
-          messages.push({
-            type: 'tool_use',
-            timestamp: entry.timestamp,
-            toolName,
-            toolInput,
-            toolCallId: entry.payload.call_id,
-          });
-        }
-
-        if (entry.type === 'response_item' && entry.payload?.type === 'function_call_output') {
-          const waitExecCallId = waitCallToExecCall.get(entry.payload.call_id);
-          if (waitExecCallId) {
-            const output = extractCodexToolOutput(entry.payload.output);
-            const runningOutput = readRunningExecOutput(output);
-            const accumulatedOutput = `${pendingExecOutput.get(waitExecCallId) || ''}${runningOutput?.content ?? output}`;
-            pendingExecOutput.set(waitExecCallId, accumulatedOutput);
-
-            if (!runningOutput && !completedExecCalls.has(waitExecCallId)) {
-              messages.push({
-                type: 'tool_result',
-                timestamp: entry.timestamp,
-                toolCallId: waitExecCallId,
-                output: accumulatedOutput,
-              });
-              completedExecCalls.add(waitExecCallId);
-            }
-            continue;
-          }
-
-          const subagent = subagentsByCallId.get(entry.payload.call_id);
-          if (subagent) {
-            const output = extractCodexToolOutput(entry.payload.output);
-            try {
-              const taskPath = readNonEmptyString((JSON.parse(output) as AnyRecord).task_name);
-              if (taskPath) {
-                subagent.agentPath = taskPath;
-                subagentsByPath.set(taskPath, subagent);
-              }
-            } catch {
-              // The sub_agent_activity event normally supplies the path.
-            }
-            continue;
-          }
-
-          if (ignoredToolCallIds.has(entry.payload.call_id)) {
-            continue;
-          }
-
-          messages.push({
-            type: 'tool_result',
-            timestamp: entry.timestamp,
-            toolCallId: entry.payload.call_id,
-            output: extractCodexToolOutput(entry.payload.output),
-          });
-        }
-
-        if (entry.type === 'response_item' && entry.payload?.type === 'custom_tool_call') {
-          let toolName = entry.payload.name || 'custom_tool';
-          const input = entry.payload.input || '';
-          let toolInput = input;
-
-          if (toolName === 'exec') {
-            const translated = translateCodexExecInput(input);
-            if (translated) {
-              toolName = translated.toolName;
-              toolInput = translated.toolInput;
-            }
-            messages.push({
-              type: 'tool_use',
-              timestamp: entry.timestamp,
-              toolName,
-              toolInput,
-              toolCallId: entry.payload.call_id,
-            });
-            execToolCallIds.add(entry.payload.call_id);
-            continue;
-          }
-
-          if (toolName === 'apply_patch') {
-            const fileMatch = String(input).match(/\*\*\* Update File: (.+)/);
-            const filePath = fileMatch ? fileMatch[1].trim() : 'unknown';
-            const lines = String(input).split('\n');
-            const oldLines: string[] = [];
-            const newLines: string[] = [];
-
-            for (const lineContent of lines) {
-              if (lineContent.startsWith('-') && !lineContent.startsWith('---')) {
-                oldLines.push(lineContent.slice(1));
-              } else if (lineContent.startsWith('+') && !lineContent.startsWith('+++')) {
-                newLines.push(lineContent.slice(1));
-              }
-            }
-
-            messages.push({
-              type: 'tool_use',
-              timestamp: entry.timestamp,
-              toolName: 'Edit',
-              toolInput: JSON.stringify({
-                file_path: filePath,
-                old_string: oldLines.join('\n'),
-                new_string: newLines.join('\n'),
-              }),
-              toolCallId: entry.payload.call_id,
-            });
-          } else {
-            messages.push({
-              type: 'tool_use',
-              timestamp: entry.timestamp,
-              toolName,
-              toolInput: input,
-              toolCallId: entry.payload.call_id,
-            });
-          }
-        }
-
-        if (entry.type === 'response_item' && entry.payload?.type === 'custom_tool_call_output') {
-          if (ignoredToolCallIds.has(entry.payload.call_id)) {
-            continue;
-          }
-
-          const output = extractCodexToolOutput(entry.payload.output);
-          if (execToolCallIds.has(entry.payload.call_id)) {
-            const runningOutput = readRunningExecOutput(output);
-            if (runningOutput) {
-              execCallByCellId.set(runningOutput.cellId, entry.payload.call_id);
-              pendingExecOutput.set(entry.payload.call_id, runningOutput.content);
-              continue;
-            }
-            completedExecCalls.add(entry.payload.call_id);
-          }
-
-          messages.push({
-            type: 'tool_result',
-            timestamp: entry.timestamp,
-            toolCallId: entry.payload.call_id,
-            output,
-          });
-        }
-      } catch {
-        // Skip malformed lines.
-      }
-    }
-
-    messages.sort(
-      (a, b) => new Date(a.timestamp || 0).getTime() - new Date(b.timestamp || 0).getTime(),
-    );
-    const total = messages.length;
-
-    if (limit !== null) {
-      const startIndex = Math.max(0, total - offset - limit);
-      const endIndex = total - offset;
-      const paginatedMessages = messages.slice(startIndex, endIndex);
-      const hasMore = startIndex > 0;
-
-      return {
-        messages: paginatedMessages,
-        total,
-        hasMore,
-        offset,
-        limit,
-        tokenUsage,
-      };
-    }
-
-    return { messages, tokenUsage };
-  } catch (error) {
-    console.error(`Error reading Codex session messages for ${sessionId}:`, error);
-    return { messages: [], total: 0, hasMore: false };
-  }
-}
-
-export class CodexSessionsProvider implements IProviderSessions {
-  /**
-   * Normalizes a persisted Codex JSONL entry.
-   *
-   * Live Codex SDK events are transformed before they reach normalizeMessage(),
-   * while history entries already use a compact message/tool shape from projects.js.
-   */
-  private normalizeHistoryEntry(raw: AnyRecord, sessionId: string | null): NormalizedMessage[] {
-    const ts = raw.timestamp || new Date().toISOString();
-    const baseId = raw.uuid || generateMessageId('codex');
-
-    if (raw.type === 'thinking' || raw.isReasoning) {
-      const thinkingContent = typeof raw.message?.content === 'string'
-        ? raw.message.content
-        : '';
-      if (!thinkingContent.trim()) {
-        return [];
-      }
-      return [createNormalizedMessage({
-        id: baseId,
-        sessionId,
-        timestamp: ts,
-        provider: PROVIDER,
-        kind: 'thinking',
-        content: thinkingContent,
-      })];
-    }
-
-    if (raw.message?.role === 'user') {
-      const content = typeof raw.message.content === 'string'
-        ? raw.message.content
-        : Array.isArray(raw.message.content)
-          ? raw.message.content
-              .map((part: string | AnyRecord) => typeof part === 'string' ? part : part?.text || '')
-              .filter(Boolean)
-              .join('\n')
-          : String(raw.message.content || '');
-      const parsedFiles = parseFilesInputTag(content);
-      const rawImages = Array.isArray(raw.images) && raw.images.length > 0 ? raw.images : undefined;
-      const files = parsedFiles.attachments.length > 0 ? parsedFiles.attachments : undefined;
-      if (!parsedFiles.text.trim() && !rawImages && !files) {
-        return [];
-      }
-      return [createNormalizedMessage({
-        id: baseId,
-        sessionId,
-        timestamp: ts,
-        provider: PROVIDER,
-        kind: 'text',
-        role: 'user',
-        content: parsedFiles.text,
-        images: rawImages,
-        files,
-      })];
-    }
-
-    if (raw.message?.role === 'assistant') {
-      const content = typeof raw.message.content === 'string'
-        ? raw.message.content
-        : Array.isArray(raw.message.content)
-          ? raw.message.content
-              .map((part: string | AnyRecord) => typeof part === 'string' ? part : part?.text || '')
-              .filter(Boolean)
-              .join('\n')
-          : '';
-      if (!content.trim()) {
-        return [];
-      }
-      return [createNormalizedMessage({
-        id: baseId,
-        sessionId,
-        timestamp: ts,
-        provider: PROVIDER,
-        kind: 'text',
-        role: 'assistant',
-        content,
-      })];
-    }
-
-    if (raw.type === 'tool_use' || raw.toolName) {
-      return [createNormalizedMessage({
-        id: baseId,
-        sessionId,
-        timestamp: ts,
-        provider: PROVIDER,
-        kind: 'tool_use',
-        toolName: raw.toolName || 'Unknown',
-        toolInput: raw.toolInput,
-        toolId: raw.toolCallId || baseId,
-      })];
-    }
-
-    if (raw.type === 'tool_result') {
-      return [createNormalizedMessage({
-        id: baseId,
-        sessionId,
-        timestamp: ts,
-        provider: PROVIDER,
-        kind: 'tool_result',
-        toolId: raw.toolCallId || '',
-        content: raw.output || '',
-        isError: Boolean(raw.isError),
-      })];
-    }
-
-    return [];
-  }
-
-  /**
-   * Normalizes either a Codex history entry or a transformed live SDK event.
-   */
-  normalizeMessage(rawMessage: unknown, sessionId: string | null): NormalizedMessage[] {
-    const raw = readObjectRecord(rawMessage);
-    if (!raw) {
-      return [];
-    }
-
-    if (raw.message?.role) {
-      return this.normalizeHistoryEntry(raw, sessionId);
-    }
-
-    const ts = raw.timestamp || new Date().toISOString();
-    const baseId = raw.uuid || generateMessageId('codex');
-
-    if (raw.type === 'item') {
-      switch (raw.itemType) {
-        case 'agent_message':
-          return [createNormalizedMessage({
-            id: baseId,
-            sessionId,
-            timestamp: ts,
-            provider: PROVIDER,
-            kind: 'text',
-            role: 'assistant',
-            content: raw.message?.content || '',
-          })];
-        case 'reasoning':
-          return [createNormalizedMessage({
-            id: baseId,
-            sessionId,
-            timestamp: ts,
-            provider: PROVIDER,
-            kind: 'thinking',
-            content: raw.message?.content || '',
-          })];
-        case 'command_execution':
-          return [createNormalizedMessage({
-            id: baseId,
-            sessionId,
-            timestamp: ts,
-            provider: PROVIDER,
-            kind: 'tool_use',
-            toolName: 'Bash',
-            toolInput: { command: raw.command },
-            toolId: baseId,
-            output: raw.output,
-            exitCode: raw.exitCode,
-            status: raw.status,
-          })];
-        case 'file_change':
-          return [createNormalizedMessage({
-            id: baseId,
-            sessionId,
-            timestamp: ts,
-            provider: PROVIDER,
-            kind: 'tool_use',
-            toolName: 'FileChanges',
-            toolInput: raw.changes,
-            toolId: baseId,
-            status: raw.status,
-          })];
-        case 'mcp_tool_call':
-          return [createNormalizedMessage({
-            id: baseId,
-            sessionId,
-            timestamp: ts,
-            provider: PROVIDER,
-            kind: 'tool_use',
-            toolName: raw.tool || 'MCP',
-            toolInput: raw.arguments,
-            toolId: baseId,
-            server: raw.server,
-            result: raw.result,
-            error: raw.error,
-            status: raw.status,
-          })];
-        case 'web_search':
-          return [createNormalizedMessage({
-            id: baseId,
-            sessionId,
-            timestamp: ts,
-            provider: PROVIDER,
-            kind: 'tool_use',
-            toolName: 'WebSearch',
-            toolInput: { query: raw.query },
-            toolId: baseId,
-          })];
-        case 'todo_list':
-          return [createNormalizedMessage({
-            id: baseId,
-            sessionId,
-            timestamp: ts,
-            provider: PROVIDER,
-            kind: 'tool_use',
-            toolName: 'TodoList',
-            toolInput: { items: raw.items },
-            toolId: baseId,
-          })];
-        case 'error':
-          return [createNormalizedMessage({
-            id: baseId,
-            sessionId,
-            timestamp: ts,
-            provider: PROVIDER,
-            kind: 'error',
-            content: raw.message?.content || 'Unknown error',
-          })];
-        default:
-          return [createNormalizedMessage({
-            id: baseId,
-            sessionId,
-            timestamp: ts,
-            provider: PROVIDER,
-            kind: 'tool_use',
-            toolName: raw.itemType || 'Unknown',
-            toolInput: raw.item || raw,
-            toolId: baseId,
-          })];
-      }
-    }
-
-    if (raw.type === 'turn_complete') {
-      return [createNormalizedMessage({
-        id: baseId,
-        sessionId,
-        timestamp: ts,
-        provider: PROVIDER,
-        kind: 'complete',
-      })];
-    }
-    if (raw.type === 'turn_failed') {
-      return [createNormalizedMessage({
-        id: baseId,
-        sessionId,
-        timestamp: ts,
-        provider: PROVIDER,
-        kind: 'error',
-        content: raw.error?.message || 'Turn failed',
-      })];
-    }
-
-    return [];
-  }
-
-  /**
-   * Loads Codex JSONL history and keeps token usage metadata when projects.js
-   * provides it.
-   */
-  async fetchHistory(
-    sessionId: string,
-    options: FetchHistoryOptions = {},
-  ): Promise<FetchHistoryResult> {
-    const { limit = null, offset = 0 } = options;
-
-    let result: CodexHistoryResult;
-    try {
-      // Load full history first so `total` reflects frontend-normalized messages,
-      // not raw JSONL records.
-      result = await getCodexSessionMessages(sessionId, null, 0);
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      console.warn(`[CodexProvider] Failed to load session ${sessionId}:`, message);
-      return { messages: [], total: 0, hasMore: false, offset: 0, limit: null };
-    }
-
-    const rawMessages = Array.isArray(result) ? result : (result.messages || []);
-    const tokenUsage = Array.isArray(result) ? undefined : result.tokenUsage;
-
-    const normalized: NormalizedMessage[] = [];
-    for (const raw of rawMessages) {
-      normalized.push(...this.normalizeHistoryEntry(raw, sessionId));
-    }
-
-    const toolResultMap = new Map<string, NormalizedMessage>();
-    for (const msg of normalized) {
-      if (msg.kind === 'tool_result' && msg.toolId) {
-        toolResultMap.set(msg.toolId, msg);
-      }
-    }
-    for (const msg of normalized) {
-      if (msg.kind === 'tool_use' && msg.toolId && toolResultMap.has(msg.toolId)) {
-        const toolResult = toolResultMap.get(msg.toolId);
-        if (toolResult) {
-          msg.toolResult = { content: toolResult.content, isError: toolResult.isError };
-        }
-      }
-    }
-
-    let total = 0;
-    for (const msg of normalized) {
-      if (msg.kind !== 'tool_result') {
-        total += 1;
-      }
-    }
-    const normalizedOffset = Math.max(0, offset);
-    const normalizedLimit = limit === null ? null : Math.max(0, limit);
-    const { page, hasMore } = sliceTailPage(normalized, normalizedLimit, normalizedOffset);
-
-    return {
-      messages: page,
-      total,
-      hasMore,
-      offset: normalizedOffset,
-      limit: normalizedLimit,
-      tokenUsage,
-    };
-  }
-}
+import fsSync from 'node:fs';
+import readline from 'node:readline';
+
+import { sessionsDb } from '@/modules/database/index.js';
+import { parseFilesInputTag, toImageAttachments } from '@/shared/image-attachments.js';
+import type { IProviderSessions } from '@/shared/interfaces.js';
+import type { AnyRecord, FetchHistoryOptions, FetchHistoryResult, NormalizedMessage } from '@/shared/types.js';
+import { createNormalizedMessage, generateMessageId, readObjectRecord, sliceTailPage } from '@/shared/utils.js';
+
+const PROVIDER = 'codex';
+
+type CodexHistoryResult =
+  | AnyRecord[]
+  | {
+      messages?: AnyRecord[];
+      total?: number;
+      hasMore?: boolean;
+      offset?: number;
+      limit?: number | null;
+      tokenUsage?: unknown;
+    };
+
+function isVisibleCodexUserMessage(payload: AnyRecord | null | undefined): boolean {
+  if (!payload || payload.type !== 'user_message') {
+    return false;
+  }
+
+  if (payload.kind && payload.kind !== 'plain') {
+    return false;
+  }
+
+  return typeof payload.message === 'string' && payload.message.trim().length > 0;
+}
+
+/**
+ * Reads the image attachments Codex records on `user_message` events.
+ * Turns sent with `local_image` input items land in `local_images` as file
+ * paths (verified against real rollout JSONL); the `images` array can carry
+ * base64 data URLs, which are passed through as inline `data` attachments so
+ * the UI can preview them without a file lookup.
+ *
+ * Exported for tests.
+ */
+export function extractCodexUserImages(
+  payload: AnyRecord | null | undefined,
+): Array<{ path?: string; data?: string }> | undefined {
+  if (!payload) {
+    return undefined;
+  }
+
+  const candidates = [
+    ...(Array.isArray(payload.local_images) ? payload.local_images : []),
+    ...(Array.isArray(payload.images) ? payload.images : []),
+  ];
+
+  const attachments: Array<{ path?: string; data?: string }> = [];
+  for (const entry of candidates) {
+    if (typeof entry !== 'string' || !entry.trim()) {
+      continue;
+    }
+    if (entry.startsWith('data:')) {
+      attachments.push({ data: entry });
+    } else {
+      attachments.push(...toImageAttachments([entry]));
+    }
+  }
+
+  return attachments.length > 0 ? attachments : undefined;
+}
+
+function extractCodexTextContent(content: unknown): string {
+  if (!Array.isArray(content)) {
+    return typeof content === 'string' ? content : '';
+  }
+
+  return content
+    .map((item) => {
+      if (!item || typeof item !== 'object') {
+        return '';
+      }
+
+      const record = item as AnyRecord;
+      if (
+        (record.type === 'input_text' || record.type === 'output_text' || record.type === 'text')
+        && typeof record.text === 'string'
+      ) {
+        return record.text;
+      }
+
+      return '';
+    })
+    .filter(Boolean)
+    .join('\n');
+}
+
+function extractCodexToolOutput(output: unknown): string {
+  if (typeof output === 'string') {
+    return output;
+  }
+
+  if (!Array.isArray(output)) {
+    return output == null ? '' : JSON.stringify(output);
+  }
+
+  return output
+    .map((item) => {
+      const record = readObjectRecord(item);
+      return typeof record?.text === 'string' ? record.text : '';
+    })
+    .filter(Boolean)
+    .join('');
+}
+
+function readRunningExecOutput(output: string): { cellId: string; content: string } | null {
+  const runningCell = /Script running with cell ID\s+(\S+)/i.exec(output);
+  if (!runningCell) {
+    return null;
+  }
+
+  const outputMarker = /\r?\nOutput:\r?\n/i.exec(output);
+  return {
+    cellId: runningCell[1],
+    content: outputMarker ? output.slice((outputMarker.index || 0) + outputMarker[0].length) : '',
+  };
+}
+
+function decodeJavaScriptStringLiteral(literal: string): string {
+  if (literal.startsWith('"')) {
+    try {
+      return JSON.parse(literal) as string;
+    } catch {
+      return literal.slice(1, -1);
+    }
+  }
+
+  return literal
+    .slice(1, -1)
+    .replace(/\\n/g, '\n')
+    .replace(/\\r/g, '\r')
+    .replace(/\\t/g, '\t')
+    .replace(/\\([\\'`])/g, '$1');
+}
+
+function extractNestedCodexCommands(source: string): string[] {
+  const commands: string[] = [];
+  const commandPattern = /(?:["']command["']|\bcommand)\s*:\s*("(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|`(?:\\.|[^`\\])*`)/gs;
+  for (const match of source.matchAll(commandPattern)) {
+    commands.push(decodeJavaScriptStringLiteral(match[1]));
+  }
+
+  if (commands.length === 0) {
+    const arrayPattern = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*\[([\s\S]*?)\]\s*;/g;
+    const stringPattern = /("(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|`(?:\\.|[^`\\])*`)/g;
+
+    for (const arrayMatch of source.matchAll(arrayPattern)) {
+      const arrayName = arrayMatch[1];
+      if (!new RegExp(`\\b${arrayName}\\.map\\s*\\(`).test(source)) {
+        continue;
+      }
+      for (const stringMatch of arrayMatch[2].matchAll(stringPattern)) {
+        commands.push(decodeJavaScriptStringLiteral(stringMatch[1]));
+      }
+    }
+  }
+
+  return commands;
+}
+
+/**
+ * Newer Codex rollouts persist the orchestration wrapper (`exec`) instead of
+ * the nested tool name. Recover the useful UI-level operation so history does
+ * not degrade into rows labelled only "exec / Parameters".
+ */
+function translateCodexExecInput(input: unknown): { toolName: string; toolInput: string } | null {
+  const source = typeof input === 'string' ? input : String(input || '');
+  if (/\btools\.(?:shell_command|exec_command)\s*\(/.test(source)) {
+    const commands = extractNestedCodexCommands(source);
+    if (commands.length > 0) {
+      return {
+        toolName: 'Bash',
+        toolInput: JSON.stringify({ command: commands.join('\n') }),
+      };
+    }
+  }
+
+  return null;
+}
+
+function humanizeCodexToolName(toolName: string): string {
+  return toolName
+    .replace(/__/g, ' ')
+    .replace(/_/g, ' ')
+    .replace(/\b\w/g, (character) => character.toUpperCase());
+}
+
+type CodexSubagentRecord = {
+  toolCallId: string;
+  message: AnyRecord;
+  agentPath?: string;
+  isComplete: boolean;
+};
+
+function parseCodexSubagentMessage(payload: AnyRecord): {
+  author: string;
+  messageType: string;
+  result: string;
+} | null {
+  const text = extractCodexTextContent(payload.content);
+  const header = /Message Type:\s*([^\r\n]+)[\s\S]*?Sender:\s*([^\r\n]+)[\s\S]*?Payload:\s*\r?\n([\s\S]*)/i.exec(text);
+  const author = readNonEmptyString(payload.author) || header?.[2]?.trim();
+  if (!author) {
+    return null;
+  }
+
+  return {
+    author,
+    messageType: header?.[1]?.trim().toUpperCase() || 'MESSAGE',
+    result: header?.[3]?.trim() || '',
+  };
+}
+
+const CODEX_COLLABORATION_CONTROL_TOOLS = new Set([
+  'followup_task',
+  'interrupt_agent',
+  'list_agents',
+  'send_message',
+  'wait_agent',
+]);
+
+function readNonEmptyString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+async function getCodexSessionMessages(
+  sessionId: string,
+  limit: number | null = null,
+  offset = 0,
+): Promise<CodexHistoryResult> {
+  try {
+    const sessionFilePath = sessionsDb.getSessionById(sessionId)?.jsonl_path;
+
+    if (!sessionFilePath) {
+      console.warn(`Codex session file not found for session ${sessionId}`);
+      return { messages: [], total: 0, hasMore: false };
+    }
+
+    const messages: AnyRecord[] = [];
+    let tokenUsage: AnyRecord | null = null;
+    const ignoredToolCallIds = new Set<string>();
+    const execToolCallIds = new Set<string>();
+    const execCallByCellId = new Map<string, string>();
+    const waitCallToExecCall = new Map<string, string>();
+    const pendingExecOutput = new Map<string, string>();
+    const completedExecCalls = new Set<string>();
+    const subagentsByCallId = new Map<string, CodexSubagentRecord>();
+    const subagentsByPath = new Map<string, CodexSubagentRecord>();
+    const fileStream = fsSync.createReadStream(sessionFilePath);
+    const rl = readline.createInterface({
+      input: fileStream,
+      crlfDelay: Infinity,
+    });
+
+    for await (const line of rl) {
+      if (!line.trim()) {
+        continue;
+      }
+
+      try {
+        const entry = JSON.parse(line) as AnyRecord;
+        if (entry.type === 'event_msg' && entry.payload?.type === 'token_count' && entry.payload?.info) {
+          const info = entry.payload.info as AnyRecord;
+          if (info.total_token_usage) {
+            const usage = info.total_token_usage as AnyRecord;
+            tokenUsage = {
+              used: usage.total_tokens || 0,
+              total: info.model_context_window || 200000,
+            };
+          }
+        }
+
+        if (
+          entry.type === 'event_msg'
+          && entry.payload?.type === 'sub_agent_activity'
+          && entry.payload.kind === 'started'
+        ) {
+          const eventId = readNonEmptyString(entry.payload.event_id);
+          const agentPath = readNonEmptyString(entry.payload.agent_path);
+          const subagent = eventId ? subagentsByCallId.get(eventId) : undefined;
+          if (subagent && agentPath) {
+            subagent.agentPath = agentPath;
+            subagentsByPath.set(agentPath, subagent);
+          }
+        }
+
+        if (entry.type === 'event_msg' && isVisibleCodexUserMessage(entry.payload as AnyRecord)) {
+          messages.push({
+            type: 'user',
+            timestamp: entry.timestamp,
+            message: {
+              role: 'user',
+              content: entry.payload.message,
+            },
+            images: extractCodexUserImages(entry.payload as AnyRecord),
+          });
+        }
+
+        if (
+          entry.type === 'response_item' &&
+          entry.payload?.type === 'message' &&
+          entry.payload.role === 'assistant'
+        ) {
+          const textContent = extractCodexTextContent(entry.payload.content);
+          if (textContent.trim()) {
+            messages.push({
+              type: 'assistant',
+              timestamp: entry.timestamp,
+              message: {
+                role: 'assistant',
+                content: textContent,
+              },
+            });
+          }
+        }
+
+        if (entry.type === 'response_item' && entry.payload?.type === 'reasoning') {
+          const summaryText = Array.isArray(entry.payload.summary)
+            ? entry.payload.summary
+                .map((item: AnyRecord) => item?.text)
+                .filter(Boolean)
+                .join('\n')
+            : '';
+
+          if (summaryText.trim()) {
+            messages.push({
+              type: 'thinking',
+              timestamp: entry.timestamp,
+              message: {
+                role: 'assistant',
+                content: summaryText,
+              },
+            });
+          }
+        }
+
+        if (entry.type === 'response_item' && entry.payload?.type === 'agent_message') {
+          const agentMessage = parseCodexSubagentMessage(entry.payload as AnyRecord);
+          if (agentMessage && agentMessage.messageType === 'FINAL_ANSWER' && agentMessage.result) {
+            let subagent = subagentsByPath.get(agentMessage.author);
+            if (!subagent) {
+              const fallbackCallId = entry.payload.id || generateMessageId('codex-subagent');
+              const taskName = agentMessage.author.split('/').filter(Boolean).pop() || 'agent';
+              const taskMessage: AnyRecord = {
+                uuid: fallbackCallId,
+                type: 'tool_use',
+                timestamp: entry.timestamp,
+                toolName: 'Task',
+                toolInput: JSON.stringify({
+                  subagent_type: 'Codex',
+                  description: humanizeCodexToolName(taskName),
+                }),
+                toolCallId: fallbackCallId,
+              };
+              messages.push(taskMessage);
+              subagent = {
+                toolCallId: fallbackCallId,
+                message: taskMessage,
+                agentPath: agentMessage.author,
+                isComplete: false,
+              };
+              subagentsByCallId.set(fallbackCallId, subagent);
+              subagentsByPath.set(agentMessage.author, subagent);
+            }
+
+            if (!subagent.isComplete) {
+              messages.push({
+                type: 'tool_result',
+                timestamp: entry.timestamp,
+                toolCallId: subagent.toolCallId,
+                output: agentMessage.result,
+              });
+              subagent.isComplete = true;
+            }
+          }
+        }
+
+        if (entry.type === 'response_item' && entry.payload?.type === 'function_call') {
+          let toolName = entry.payload.name;
+          let toolInput = entry.payload.arguments;
+
+          if (toolName === 'spawn_agent') {
+            let taskName = 'agent';
+            try {
+              const args = JSON.parse(String(entry.payload.arguments || '{}')) as AnyRecord;
+              taskName = readNonEmptyString(args.task_name) || taskName;
+            } catch {
+              // The activity event can still provide the canonical agent path.
+            }
+
+            const taskMessage: AnyRecord = {
+              uuid: entry.payload.call_id,
+              type: 'tool_use',
+              timestamp: entry.timestamp,
+              toolName: 'Task',
+              toolInput: JSON.stringify({
+                subagent_type: 'Codex',
+                description: humanizeCodexToolName(taskName),
+              }),
+              toolCallId: entry.payload.call_id,
+            };
+            messages.push(taskMessage);
+            subagentsByCallId.set(entry.payload.call_id, {
+              toolCallId: entry.payload.call_id,
+              message: taskMessage,
+              isComplete: false,
+            });
+            ignoredToolCallIds.add(entry.payload.call_id);
+            continue;
+          }
+
+          if (toolName === 'wait') {
+            try {
+              const args = JSON.parse(String(entry.payload.arguments || '{}')) as AnyRecord;
+              const cellId = String(args.cell_id || '');
+              const execCallId = execCallByCellId.get(cellId);
+              if (execCallId) {
+                waitCallToExecCall.set(entry.payload.call_id, execCallId);
+              }
+            } catch {
+              // Suppress the orchestration wait even when its payload is malformed.
+            }
+            ignoredToolCallIds.add(entry.payload.call_id);
+            continue;
+          }
+
+          if (CODEX_COLLABORATION_CONTROL_TOOLS.has(toolName)) {
+            ignoredToolCallIds.add(entry.payload.call_id);
+            continue;
+          }
+
+          if (toolName === 'shell_command') {
+            toolName = 'Bash';
+            try {
+              const args = JSON.parse(entry.payload.arguments) as AnyRecord;
+              toolInput = JSON.stringify({ command: args.command });
+            } catch {
+              // Keep original arguments when parsing fails.
+            }
+          }
+
+          messages.push({
+            type: 'tool_use',
+            timestamp: entry.timestamp,
+            toolName,
+            toolInput,
+            toolCallId: entry.payload.call_id,
+          });
+        }
+
+        if (entry.type === 'response_item' && entry.payload?.type === 'function_call_output') {
+          const waitExecCallId = waitCallToExecCall.get(entry.payload.call_id);
+          if (waitExecCallId) {
+            const output = extractCodexToolOutput(entry.payload.output);
+            const runningOutput = readRunningExecOutput(output);
+            const accumulatedOutput = `${pendingExecOutput.get(waitExecCallId) || ''}${runningOutput?.content ?? output}`;
+            pendingExecOutput.set(waitExecCallId, accumulatedOutput);
+
+            if (!runningOutput && !completedExecCalls.has(waitExecCallId)) {
+              messages.push({
+                type: 'tool_result',
+                timestamp: entry.timestamp,
+                toolCallId: waitExecCallId,
+                output: accumulatedOutput,
+              });
+              completedExecCalls.add(waitExecCallId);
+            }
+            continue;
+          }
+
+          const subagent = subagentsByCallId.get(entry.payload.call_id);
+          if (subagent) {
+            const output = extractCodexToolOutput(entry.payload.output);
+            try {
+              const taskPath = readNonEmptyString((JSON.parse(output) as AnyRecord).task_name);
+              if (taskPath) {
+                subagent.agentPath = taskPath;
+                subagentsByPath.set(taskPath, subagent);
+              }
+            } catch {
+              // The sub_agent_activity event normally supplies the path.
+            }
+            continue;
+          }
+
+          if (ignoredToolCallIds.has(entry.payload.call_id)) {
+            continue;
+          }
+
+          messages.push({
+            type: 'tool_result',
+            timestamp: entry.timestamp,
+            toolCallId: entry.payload.call_id,
+            output: extractCodexToolOutput(entry.payload.output),
+          });
+        }
+
+        if (entry.type === 'response_item' && entry.payload?.type === 'custom_tool_call') {
+          let toolName = entry.payload.name || 'custom_tool';
+          const input = entry.payload.input || '';
+          let toolInput = input;
+
+          if (toolName === 'exec') {
+            const translated = translateCodexExecInput(input);
+            if (translated) {
+              toolName = translated.toolName;
+              toolInput = translated.toolInput;
+            }
+            messages.push({
+              type: 'tool_use',
+              timestamp: entry.timestamp,
+              toolName,
+              toolInput,
+              toolCallId: entry.payload.call_id,
+            });
+            execToolCallIds.add(entry.payload.call_id);
+            continue;
+          }
+
+          if (toolName === 'apply_patch') {
+            const fileMatch = String(input).match(/\*\*\* Update File: (.+)/);
+            const filePath = fileMatch ? fileMatch[1].trim() : 'unknown';
+            const lines = String(input).split('\n');
+            const oldLines: string[] = [];
+            const newLines: string[] = [];
+
+            for (const lineContent of lines) {
+              if (lineContent.startsWith('-') && !lineContent.startsWith('---')) {
+                oldLines.push(lineContent.slice(1));
+              } else if (lineContent.startsWith('+') && !lineContent.startsWith('+++')) {
+                newLines.push(lineContent.slice(1));
+              }
+            }
+
+            messages.push({
+              type: 'tool_use',
+              timestamp: entry.timestamp,
+              toolName: 'Edit',
+              toolInput: JSON.stringify({
+                file_path: filePath,
+                old_string: oldLines.join('\n'),
+                new_string: newLines.join('\n'),
+              }),
+              toolCallId: entry.payload.call_id,
+            });
+          } else {
+            messages.push({
+              type: 'tool_use',
+              timestamp: entry.timestamp,
+              toolName,
+              toolInput: input,
+              toolCallId: entry.payload.call_id,
+            });
+          }
+        }
+
+        if (entry.type === 'response_item' && entry.payload?.type === 'custom_tool_call_output') {
+          if (ignoredToolCallIds.has(entry.payload.call_id)) {
+            continue;
+          }
+
+          const output = extractCodexToolOutput(entry.payload.output);
+          if (execToolCallIds.has(entry.payload.call_id)) {
+            const runningOutput = readRunningExecOutput(output);
+            if (runningOutput) {
+              execCallByCellId.set(runningOutput.cellId, entry.payload.call_id);
+              pendingExecOutput.set(entry.payload.call_id, runningOutput.content);
+              continue;
+            }
+            completedExecCalls.add(entry.payload.call_id);
+          }
+
+          messages.push({
+            type: 'tool_result',
+            timestamp: entry.timestamp,
+            toolCallId: entry.payload.call_id,
+            output,
+          });
+        }
+      } catch {
+        // Skip malformed lines.
+      }
+    }
+
+    messages.sort(
+      (a, b) => new Date(a.timestamp || 0).getTime() - new Date(b.timestamp || 0).getTime(),
+    );
+    const total = messages.length;
+
+    if (limit !== null) {
+      const startIndex = Math.max(0, total - offset - limit);
+      const endIndex = total - offset;
+      const paginatedMessages = messages.slice(startIndex, endIndex);
+      const hasMore = startIndex > 0;
+
+      return {
+        messages: paginatedMessages,
+        total,
+        hasMore,
+        offset,
+        limit,
+        tokenUsage,
+      };
+    }
+
+    return { messages, tokenUsage };
+  } catch (error) {
+    console.error(`Error reading Codex session messages for ${sessionId}:`, error);
+    return { messages: [], total: 0, hasMore: false };
+  }
+}
+
+export class CodexSessionsProvider implements IProviderSessions {
+  /**
+   * Normalizes a persisted Codex JSONL entry.
+   *
+   * Live Codex SDK events are transformed before they reach normalizeMessage(),
+   * while history entries already use a compact message/tool shape from projects.js.
+   */
+  private normalizeHistoryEntry(raw: AnyRecord, sessionId: string | null): NormalizedMessage[] {
+    const ts = raw.timestamp || new Date().toISOString();
+    const baseId = raw.uuid || generateMessageId('codex');
+
+    if (raw.type === 'thinking' || raw.isReasoning) {
+      const thinkingContent = typeof raw.message?.content === 'string'
+        ? raw.message.content
+        : '';
+      if (!thinkingContent.trim()) {
+        return [];
+      }
+      return [createNormalizedMessage({
+        id: baseId,
+        sessionId,
+        timestamp: ts,
+        provider: PROVIDER,
+        kind: 'thinking',
+        content: thinkingContent,
+      })];
+    }
+
+    if (raw.message?.role === 'user') {
+      const content = typeof raw.message.content === 'string'
+        ? raw.message.content
+        : Array.isArray(raw.message.content)
+          ? raw.message.content
+              .map((part: string | AnyRecord) => typeof part === 'string' ? part : part?.text || '')
+              .filter(Boolean)
+              .join('\n')
+          : String(raw.message.content || '');
+      const parsedFiles = parseFilesInputTag(content);
+      const rawImages = Array.isArray(raw.images) && raw.images.length > 0 ? raw.images : undefined;
+      const files = parsedFiles.attachments.length > 0 ? parsedFiles.attachments : undefined;
+      if (!parsedFiles.text.trim() && !rawImages && !files) {
+        return [];
+      }
+      return [createNormalizedMessage({
+        id: baseId,
+        sessionId,
+        timestamp: ts,
+        provider: PROVIDER,
+        kind: 'text',
+        role: 'user',
+        content: parsedFiles.text,
+        images: rawImages,
+        files,
+      })];
+    }
+
+    if (raw.message?.role === 'assistant') {
+      const content = typeof raw.message.content === 'string'
+        ? raw.message.content
+        : Array.isArray(raw.message.content)
+          ? raw.message.content
+              .map((part: string | AnyRecord) => typeof part === 'string' ? part : part?.text || '')
+              .filter(Boolean)
+              .join('\n')
+          : '';
+      if (!content.trim()) {
+        return [];
+      }
+      return [createNormalizedMessage({
+        id: baseId,
+        sessionId,
+        timestamp: ts,
+        provider: PROVIDER,
+        kind: 'text',
+        role: 'assistant',
+        content,
+      })];
+    }
+
+    if (raw.type === 'tool_use' || raw.toolName) {
+      return [createNormalizedMessage({
+        id: baseId,
+        sessionId,
+        timestamp: ts,
+        provider: PROVIDER,
+        kind: 'tool_use',
+        toolName: raw.toolName || 'Unknown',
+        toolInput: raw.toolInput,
+        toolId: raw.toolCallId || baseId,
+      })];
+    }
+
+    if (raw.type === 'tool_result') {
+      return [createNormalizedMessage({
+        id: baseId,
+        sessionId,
+        timestamp: ts,
+        provider: PROVIDER,
+        kind: 'tool_result',
+        toolId: raw.toolCallId || '',
+        content: raw.output || '',
+        isError: Boolean(raw.isError),
+      })];
+    }
+
+    return [];
+  }
+
+  /**
+   * Normalizes either a Codex history entry or a transformed live SDK event.
+   */
+  normalizeMessage(rawMessage: unknown, sessionId: string | null): NormalizedMessage[] {
+    const raw = readObjectRecord(rawMessage);
+    if (!raw) {
+      return [];
+    }
+
+    if (raw.message?.role) {
+      return this.normalizeHistoryEntry(raw, sessionId);
+    }
+
+    const ts = raw.timestamp || new Date().toISOString();
+    const baseId = raw.uuid || generateMessageId('codex');
+
+    if (raw.type === 'item') {
+      switch (raw.itemType) {
+        case 'agent_message':
+          return [createNormalizedMessage({
+            id: baseId,
+            sessionId,
+            timestamp: ts,
+            provider: PROVIDER,
+            kind: 'text',
+            role: 'assistant',
+            content: raw.message?.content || '',
+          })];
+        case 'reasoning':
+          return [createNormalizedMessage({
+            id: baseId,
+            sessionId,
+            timestamp: ts,
+            provider: PROVIDER,
+            kind: 'thinking',
+            content: raw.message?.content || '',
+          })];
+        case 'command_execution':
+          return [createNormalizedMessage({
+            id: baseId,
+            sessionId,
+            timestamp: ts,
+            provider: PROVIDER,
+            kind: 'tool_use',
+            toolName: 'Bash',
+            toolInput: { command: raw.command },
+            toolId: baseId,
+            output: raw.output,
+            exitCode: raw.exitCode,
+            status: raw.status,
+          })];
+        case 'file_change':
+          return [createNormalizedMessage({
+            id: baseId,
+            sessionId,
+            timestamp: ts,
+            provider: PROVIDER,
+            kind: 'tool_use',
+            toolName: 'FileChanges',
+            toolInput: raw.changes,
+            toolId: baseId,
+            status: raw.status,
+          })];
+        case 'mcp_tool_call':
+          return [createNormalizedMessage({
+            id: baseId,
+            sessionId,
+            timestamp: ts,
+            provider: PROVIDER,
+            kind: 'tool_use',
+            toolName: raw.tool || 'MCP',
+            toolInput: raw.arguments,
+            toolId: baseId,
+            server: raw.server,
+            result: raw.result,
+            error: raw.error,
+            status: raw.status,
+          })];
+        case 'web_search':
+          return [createNormalizedMessage({
+            id: baseId,
+            sessionId,
+            timestamp: ts,
+            provider: PROVIDER,
+            kind: 'tool_use',
+            toolName: 'WebSearch',
+            toolInput: { query: raw.query },
+            toolId: baseId,
+          })];
+        case 'todo_list':
+          return [createNormalizedMessage({
+            id: baseId,
+            sessionId,
+            timestamp: ts,
+            provider: PROVIDER,
+            kind: 'tool_use',
+            toolName: 'TodoList',
+            toolInput: { items: raw.items },
+            toolId: baseId,
+          })];
+        case 'error':
+          return [createNormalizedMessage({
+            id: baseId,
+            sessionId,
+            timestamp: ts,
+            provider: PROVIDER,
+            kind: 'error',
+            content: raw.message?.content || 'Unknown error',
+          })];
+        default:
+          return [createNormalizedMessage({
+            id: baseId,
+            sessionId,
+            timestamp: ts,
+            provider: PROVIDER,
+            kind: 'tool_use',
+            toolName: raw.itemType || 'Unknown',
+            toolInput: raw.item || raw,
+            toolId: baseId,
+          })];
+      }
+    }
+
+    if (raw.type === 'turn_complete') {
+      return [createNormalizedMessage({
+        id: baseId,
+        sessionId,
+        timestamp: ts,
+        provider: PROVIDER,
+        kind: 'complete',
+      })];
+    }
+    if (raw.type === 'turn_failed') {
+      return [createNormalizedMessage({
+        id: baseId,
+        sessionId,
+        timestamp: ts,
+        provider: PROVIDER,
+        kind: 'error',
+        content: raw.error?.message || 'Turn failed',
+      })];
+    }
+
+    return [];
+  }
+
+  /**
+   * Loads Codex JSONL history and keeps token usage metadata when projects.js
+   * provides it.
+   */
+  async fetchHistory(
+    sessionId: string,
+    options: FetchHistoryOptions = {},
+  ): Promise<FetchHistoryResult> {
+    const { limit = null, offset = 0 } = options;
+
+    let result: CodexHistoryResult;
+    try {
+      // Load full history first so `total` reflects frontend-normalized messages,
+      // not raw JSONL records.
+      result = await getCodexSessionMessages(sessionId, null, 0);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.warn(`[CodexProvider] Failed to load session ${sessionId}:`, message);
+      return { messages: [], total: 0, hasMore: false, offset: 0, limit: null };
+    }
+
+    const rawMessages = Array.isArray(result) ? result : (result.messages || []);
+    const tokenUsage = Array.isArray(result) ? undefined : result.tokenUsage;
+
+    const normalized: NormalizedMessage[] = [];
+    for (const raw of rawMessages) {
+      normalized.push(...this.normalizeHistoryEntry(raw, sessionId));
+    }
+
+    const toolResultMap = new Map<string, NormalizedMessage>();
+    for (const msg of normalized) {
+      if (msg.kind === 'tool_result' && msg.toolId) {
+        toolResultMap.set(msg.toolId, msg);
+      }
+    }
+    for (const msg of normalized) {
+      if (msg.kind === 'tool_use' && msg.toolId && toolResultMap.has(msg.toolId)) {
+        const toolResult = toolResultMap.get(msg.toolId);
+        if (toolResult) {
+          msg.toolResult = { content: toolResult.content, isError: toolResult.isError };
+        }
+      }
+    }
+
+    let total = 0;
+    for (const msg of normalized) {
+      if (msg.kind !== 'tool_result') {
+        total += 1;
+      }
+    }
+    const normalizedOffset = Math.max(0, offset);
+    const normalizedLimit = limit === null ? null : Math.max(0, limit);
+    const { page, hasMore } = sliceTailPage(normalized, normalizedLimit, normalizedOffset);
+
+    return {
+      messages: page,
+      total,
+      hasMore,
+      offset: normalizedOffset,
+      limit: normalizedLimit,
+      tokenUsage,
+    };
+  }
+}