byterover-cli 0.2.0 → 0.3.0

package/dist/infra/parsers/raw/raw-codex-service.d.ts

@@ -0,0 +1,313 @@
+/**
+ * Codex Raw Service
+ * Consolidates CodexParser + CodexRawParser
+ * Parses JSONL transcript files from ~/.codex/sessions/
+ */
+import { Agent } from '../../../core/domain/entities/agent.js';
+import { IRawParserService } from '../../../core/interfaces/parser/i-raw-parser-service.js';
+/**
+ * Codex Raw Service
+ * Handles extraction of Codex sessions from JSONL transcript files
+ */
+export declare class CodexRawService implements IRawParserService {
+    private ide;
+    /**
+     * Initialize Codex Raw Service
+     *
+     * @param ide - The IDE type (Codex)
+     */
+    constructor(ide: Agent);
+    /**
+     * Main entry point - Parse Codex sessions from a custom directory
+     *
+     * Parses all JSONL transcript files from a Codex sessions directory,
+     * extracts session information, and writes normalized JSON files to output directory.
+     * Organizes output by date (YYYY-MM-DD) matching Codex's original directory structure.
+     * Returns success status.
+     *
+     * @param customDir - Path to directory containing Codex session files
+     * @param outputDir - Optional output directory (defaults to process.cwd()/.brv/logs/{ide}/raw)
+     * @returns Promise resolving to true if parsing succeeded, false otherwise
+     */
+    parse(customDir: string, outputDir?: string): Promise<boolean>;
+    /**
+     * Build token usage object with optional cache tokens
+     *
+     * Constructs a token usage metrics object, including cache tokens only if they're
+     * greater than zero. Calculates total tokens as sum of input and output.
+     *
+     * @param cacheTokens - Number of cached input tokens
+     * @param inputTokens - Number of input tokens used
+     * @param outputTokens - Number of output tokens generated
+     * @returns Token usage object with optional cacheTokens and calculated total
+     */
+    private buildTokenUsageObject;
+    /**
+     * Calculate aggregate session metadata from transcript entries
+     *
+     * Aggregates token usage, counts message types, extracts timestamps and workspace information.
+     * Returns comprehensive metadata including token costs, message counts, duration, and session details.
+     *
+     * @param entries - Array of transcript entries from JSONL file
+     * @param messages - Parsed messages array (for count verification)
+     * @param logPath - Log file path (used to extract workspace information)
+     * @param sessionMeta - Extracted session metadata (may be null)
+     * @returns RawCodexSessionMetadata object with aggregated statistics
+     */
+    private calculateMetadata;
+    /**
+     * Calculate total token usage from transcript entries
+     *
+     * Aggregates token counts from all token_count event messages in the transcript.
+     * Includes input tokens, output tokens, and cached input tokens.
+     *
+     * @param entries - Array of transcript entries to analyze
+     * @returns Object with aggregated cacheTokens, inputTokens, and outputTokens
+     */
+    private calculateTokenUsage;
+    /**
+     * Convert Codex content block to normalized content block
+     *
+     * Transforms a Codex-specific content block into a standardized ContentBlock format.
+     * Handles tool_use blocks (preserves id, input, name) and text blocks (normalizes types).
+     * Converts input_text type to text type for consistency.
+     *
+     * @param block - Codex content block to convert
+     * @returns Normalized ContentBlock object
+     */
+    private convertCodexContentBlockToContentBlock;
+    /**
+     * Convert Codex transcript entries to normalized messages
+     *
+     * Transforms raw JSONL transcript entries (messages, function calls, reasoning, token counts) into
+     * standardized RawCodexRawMessage objects. Tracks token usage and reasoning context across entries,
+     * maintaining order and relationships between tool calls and responses.
+     *
+     * @param entries - Array of transcript entries from JSONL file
+     * @returns Array of normalized RawCodexRawMessage objects
+     */
+    private convertToMessages;
+    /**
+     * Convert transcript entry to raw entry format
+     *
+     * Transforms a transcript entry into the raw entry storage format, filtering entries without payloads
+     * and converting ISO timestamp strings to millisecond timestamps. Validates entry types and applies
+     * fallback type for invalid entries.
+     *
+     * @param entry - Transcript entry to convert
+     * @returns Converted RawCodexRawEntry object, or null if entry has no payload
+     */
+    private convertTranscriptEntryToRawEntry;
+    /**
+     * Count user and assistant messages in a message array
+     *
+     * Iterates through messages and counts the total number of user and assistant messages.
+     * Used for metadata tracking and session statistics.
+     *
+     * @param messages - Array of messages to count
+     * @returns Object with assistantCount and userCount totals
+     */
+    private countMessageTypes;
+    /**
+     * Extract and normalize content blocks from message content
+     *
+     * Handles multiple content formats: null/undefined (empty array), strings (wrapped as text block),
+     * arrays of blocks/strings (normalized to RawCodexContentBlock array), and objects.
+     * Produces consistent RawCodexContentBlock array output for consistent processing.
+     *
+     * @param content - Raw message content in various formats
+     * @returns Array of normalized RawCodexContentBlock objects
+     */
+    private extractContentBlocks;
+    /**
+     * Extract session ID from Codex log file path
+     *
+     * Parses the filename from the log path to extract the session ID.
+     * Codex session IDs are typically UUIDs in the JSONL filename.
+     * Removes the .jsonl extension to get the session ID.
+     *
+     * @param logPath - Path to Codex session log file
+     * @returns Session ID extracted from the filename
+     */
+    private extractSessionId;
+    /**
+     * Extract session metadata from transcript entries
+     *
+     * Searches transcript entries for session_meta type entries and validates them.
+     * Returns the session metadata payload (containing model, CLI version, timestamp, git info).
+     * Returns null if no valid session metadata is found.
+     *
+     * @param entries - Array of transcript entries to search
+     * @returns Extracted RawCodexSessionMeta payload, or null if not found
+     */
+    private extractSessionMeta;
+    /**
+     * Extract session start and end timestamps
+     *
+     * Collects timestamps from transcript entries, filters empty values, sorts chronologically.
+     * Prefers session metadata timestamp for start time if available, otherwise uses first entry timestamp.
+     * Returns last timestamp as end time, or undefined if only one timestamp exists.
+     *
+     * @param entries - Array of transcript entries with optional timestamp fields
+     * @param sessionMeta - Optional session metadata containing preferred start timestamp
+     * @returns Object with startedAt and optional endedAt ISO timestamp strings
+     */
+    private extractTimestamps;
+    /**
+     * Extract session title from first user message
+     *
+     * Uses the first line of the first user message as the session title.
+     * Handles both string and array content formats, extracting text blocks from arrays.
+     * Truncates to TITLE_MAX_LENGTH (100 chars) and appends "..." if truncated.
+     * Returns default title if no user messages found or first message is empty.
+     *
+     * @param messages - Array of parsed session messages
+     * @returns Session title string (max 100 characters)
+     */
+    private extractTitle;
+    /**
+     * Extract workspace information from session metadata and log path
+     *
+     * Extracts workspace path and repository information from session metadata (preferred)
+     * or falls back to log path if metadata is unavailable. Includes repository name and
+     * optional git URL if available in session metadata.
+     *
+     * @param logPath - Codex session log file path (used as fallback)
+     * @param sessionMeta - Optional session metadata containing workspace and git info
+     * @returns Object with workspace path and optional repository name/url
+     */
+    private extractWorkspace;
+    /**
+     * Type guard for event payload
+     *
+     * Checks if a payload is a valid RawCodexEventPayload by verifying it's an object
+     * with a type field matching token_count or agent_reasoning event types.
+     *
+     * @param payload - Value to check
+     * @returns True if payload is a valid RawCodexEventPayload, false otherwise
+     */
+    private isEventPayload;
+    /**
+     * Type guard for response payload
+     *
+     * Checks if a payload is a valid RawCodexResponsePayload by verifying it's an object
+     * with a type field matching one of: function_call, function_call_output, message, or reasoning.
+     *
+     * @param payload - Value to check
+     * @returns True if payload is a valid RawCodexResponsePayload, false otherwise
+     */
+    private isResponsePayload;
+    /**
+     * Type guard for session meta payload
+     *
+     * Checks if a payload is a valid RawCodexSessionMetaPayload by verifying it's an object
+     * containing at least one of: model_provider, cli_version, or timestamp fields.
+     *
+     * @param payload - Value to check
+     * @returns True if payload is a valid RawCodexSessionMetaPayload, false otherwise
+     */
+    private isSessionMetaPayload;
+    /**
+     * Check if entry is a token count event
+     *
+     * Validates that an entry is an event_msg type with an event payload of type 'token_count'
+     * and contains token usage information (info field).
+     *
+     * @param entry - Transcript entry to check
+     * @returns True if entry is a valid token count event, false otherwise
+     */
+    private isTokenCountEntry;
+    /**
+     * Parse all Codex session logs in a directory
+     *
+     * Finds all JSONL files in the directory (including subdirectories), parses them in sequence,
+     * and returns array of successfully parsed sessions sorted by start time.
+     * Collects and reports any parse errors without failing completely.
+     *
+     * @param dirPath - Path to directory containing JSONL session files
+     * @returns Promise resolving to array of parsed RawCodexRawSession objects
+     * @throws Error if directory cannot be read
+     */
+    private parseSessionDirectory;
+    /**
+     * Parse a single Codex session log file
+     *
+     * Validates log file format, reads JSONL content, parses each line as a transcript entry,
+     * converts entries to messages, extracts session metadata, calculates aggregated statistics,
+     * and extracts session title. Handles token usage, function calls, and reasoning payloads.
+     *
+     * @param logPath - Absolute path to Codex session JSONL file
+     * @returns Promise resolving to parsed RawCodexRawSession object
+     * @throws Error if file is invalid or cannot be parsed
+     */
+    private parseSessionLog;
+    /**
+     * Process function call payload and add to last message
+     *
+     * Extracts function call information from a function_call payload and appends it as a tool_use
+     * content block to the last message. Converts string arguments to parsed objects.
+     * If last message content is a string, converts it to an array before adding tool block.
+     *
+     * @param payload - Function call payload containing name, arguments, and call ID
+     * @param messages - Messages array to update (modifies last message in place)
+     */
+    private processFunctionCall;
+    /**
+     * Process function call output and attach to corresponding tool use block
+     *
+     * Finds the most recent tool_use block in the last message and appends the function output to it.
+     * The output field contains the result of the function call execution.
+     *
+     * @param payload - Function call output payload containing output data
+     * @param messages - Messages array to update (modifies last message in place)
+     */
+    private processFunctionCallOutput;
+    /**
+     * Process message payload and add to messages array
+     *
+     * Converts a message payload into a normalized RawCodexRawMessage and appends to messages array.
+     * Handles content block conversion, attaches token usage and reasoning context if available.
+     * Collapses single text blocks to strings for backward compatibility.
+     *
+     * @param payload - Message payload containing role and content
+     * @param messages - Messages array to update (appends new message)
+     * @param timestamp - ISO timestamp for the message
+     * @param currentTokenUsage - Optional token usage metrics to attach to message
+     * @param currentReasoning - Optional reasoning content to attach to message
+     */
+    private processMessage;
+    /**
+     * Process reasoning payload and extract reasoning text summary
+     *
+     * Extracts reasoning content from a reasoning payload by filtering summary items of type 'summary_text'
+     * and joining their text content. Returns null if no valid reasoning content is found.
+     *
+     * @param payload - Reasoning payload containing summary array
+     * @returns Extracted reasoning text or null if no valid content found
+     */
+    private processReasoningPayload;
+    /**
+     * Safely parse JSON string or return object as-is
+     *
+     * Attempts to parse a JSON string. If input is already an object, returns it directly.
+     * Returns empty object on parse errors or non-string/object inputs.
+     * Used for defensive parsing of tool call arguments.
+     *
+     * @param jsonString - String to parse or object to validate
+     * @returns Parsed object or empty object if parsing fails
+     */
+    private safeJsonParse;
+    /**
+     * Validate Codex log file format and existence
+     *
+     * Checks three validation criteria:
+     * 1. Path contains /.codex/sessions/ directory marker
+     * 2. File has .jsonl extension
+     * 3. File exists on filesystem
+     * Returns false silently if any check fails.
+     *
+     * @param logPath - Path to file to validate
+     * @returns Promise resolving to true if file is valid Codex log file, false otherwise
+     */
+    private validateLogFile;
+}