claude-code-workflow 6.3.18 → 6.3.19

package/ccw/src/tools/cli-output-converter.ts

@@ -0,0 +1,1237 @@
+/**
+ * CLI Output Converter
+ * Converts raw CLI tool output into structured Intermediate Representation (IR)
+ *
+ * Purpose: Decouple output parsing from consumption scenarios (View, Storage, Resume)
+ * Supports: Plain text, JSON Lines, and other structured formats
+ */
+
+// ========== Type Definitions ==========
+
+/**
+ * Unified output unit types for the intermediate representation layer
+ */
+export type CliOutputUnitType =
+  | 'stdout'         // Standard output text
+  | 'stderr'         // Standard error text
+  | 'thought'        // AI reasoning/thinking
+  | 'code'           // Code block content
+  | 'file_diff'      // File modification diff
+  | 'progress'       // Progress updates
+  | 'metadata'       // Session/execution metadata
+  | 'system'         // System events/messages
+  | 'tool_call';     // Tool invocation/result (Gemini tool_use/tool_result)
+
+/**
+ * Intermediate Representation unit
+ * Common structure for all CLI output chunks
+ */
+export interface CliOutputUnit<T = any> {
+  type: CliOutputUnitType;
+  content: T;
+  timestamp: string;  // ISO 8601 format
+}
+
+// ========== Parser Interface ==========
+
+/**
+ * Parser interface for converting raw output into IR
+ */
+export interface IOutputParser {
+  /**
+   * Parse a chunk of data from stdout/stderr stream
+   * @param chunk - Raw buffer from stream
+   * @param streamType - Source stream (stdout or stderr)
+   * @returns Array of parsed output units
+   */
+  parse(chunk: Buffer, streamType: 'stdout' | 'stderr'): CliOutputUnit[];
+
+  /**
+   * Flush any remaining buffered data
+   * Called when stream ends to ensure no data is lost
+   * @returns Array of remaining output units
+   */
+  flush(): CliOutputUnit[];
+}
+
+// ========== Plain Text Parser ==========
+
+/**
+ * PlainTextParser - Converts plain text output to IR
+ * Simply wraps text in appropriate type envelope
+ */
+export class PlainTextParser implements IOutputParser {
+  parse(chunk: Buffer, streamType: 'stdout' | 'stderr'): CliOutputUnit[] {
+    const text = chunk.toString('utf8');
+
+    if (!text) {
+      return [];
+    }
+
+    return [{
+      type: streamType,
+      content: text,
+      timestamp: new Date().toISOString()
+    }];
+  }
+
+  /**
+   * Flush any remaining buffered data
+   * Called when stream ends to ensure no data is lost
+   *
+   * Note: PlainTextParser does not buffer data internally, so this method
+   * always returns an empty array. Other parsers (e.g., JsonLinesParser)
+   * may have buffered incomplete lines that need to be flushed.
+   *
+   * @returns Array of remaining output units (always empty for PlainTextParser)
+   */
+  flush(): CliOutputUnit[] {
+    // Plain text parser has no internal buffer
+    return [];
+  }
+}
+
+// ========== JSON Lines Parser ==========
+
+/**
+ * JsonLinesParser - Parses newline-delimited JSON output
+ *
+ * Features:
+ * - Handles incomplete lines across chunks
+ * - Maps JSON events to appropriate IR types
+ * - Falls back to stdout for unparseable lines
+ * - Robust error handling for malformed JSON
+ */
+export class JsonLinesParser implements IOutputParser {
+  private buffer: string = '';
+
+  /**
+   * Classify non-JSON content to determine appropriate output type
+   * Helps distinguish real errors from normal progress/output sent to stderr
+   * (Some CLI tools like Codex send all progress info to stderr)
+   */
+  private classifyNonJsonContent(content: string, originalType: 'stdout' | 'stderr'): 'stdout' | 'stderr' {
+    // If it came from stdout, keep it as stdout
+    if (originalType === 'stdout') {
+      return 'stdout';
+    }
+
+    // Check if content looks like an actual error
+    const errorPatterns = [
+      /^error:/i,
+      /^fatal:/i,
+      /^failed:/i,
+      /^exception:/i,
+      /\bERROR\b/,
+      /\bFATAL\b/,
+      /\bFAILED\b/,
+      /\bpanic:/i,
+      /traceback \(most recent/i,
+      /syntaxerror:/i,
+      /typeerror:/i,
+      /referenceerror:/i,
+      /\bstack trace\b/i,
+      /\bat line \d+\b/i,
+      /permission denied/i,
+      /access denied/i,
+      /authentication failed/i,
+      /connection refused/i,
+      /network error/i,
+      /unable to connect/i,
+    ];
+
+    for (const pattern of errorPatterns) {
+      if (pattern.test(content)) {
+        return 'stderr';
+      }
+    }
+
+    // Check for common CLI progress/info patterns that are NOT errors
+    const progressPatterns = [
+      /^[-=]+$/,                    // Separators: ----, ====
+      /^\s*\d+\s*$/,               // Just numbers
+      /tokens?\s*(used|count)/i,   // Token counts
+      /model:/i,                   // Model info
+      /session\s*id:/i,            // Session info
+      /workdir:/i,                 // Working directory
+      /provider:/i,                // Provider info
+      /^(user|assistant|codex|claude|gemini)$/i,  // Role labels
+      /^mcp:/i,                    // MCP status
+      /^[-\s]*$/,                  // Empty or whitespace/dashes
+    ];
+
+    for (const pattern of progressPatterns) {
+      if (pattern.test(content)) {
+        return 'stdout';  // Treat as normal output, not error
+      }
+    }
+
+    // Default: if stderr but doesn't look like an error, treat as stdout
+    // This handles CLI tools that send everything to stderr (like Codex)
+    return 'stdout';
+  }
+
+  parse(chunk: Buffer, streamType: 'stdout' | 'stderr'): CliOutputUnit[] {
+    const text = chunk.toString('utf8');
+    this.buffer += text;
+
+    const units: CliOutputUnit[] = [];
+    const lines = this.buffer.split('\n');
+
+    // Keep the last incomplete line in buffer
+    this.buffer = lines.pop() || '';
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed) {
+        continue;
+      }
+
+      // Try to parse as JSON
+      let parsed: any;
+      try {
+        parsed = JSON.parse(trimmed);
+      } catch {
+        // Not valid JSON, treat as plain text
+        // For stderr content, check if it's actually an error or just normal output
+        // (Some CLI tools like Codex send all progress info to stderr)
+        const effectiveType = this.classifyNonJsonContent(line, streamType);
+        units.push({
+          type: effectiveType,
+          content: line,
+          timestamp: new Date().toISOString()
+        });
+        continue;
+      }
+
+      // Map JSON structure to IR type
+      const unit = this.mapJsonToIR(parsed, streamType);
+      if (unit) {
+        units.push(unit);
+      }
+    }
+
+    return units;
+  }
+
+  flush(): CliOutputUnit[] {
+    const units: CliOutputUnit[] = [];
+
+    if (this.buffer.trim()) {
+      // Try to parse remaining buffer
+      try {
+        const parsed = JSON.parse(this.buffer.trim());
+        const unit = this.mapJsonToIR(parsed, 'stdout');
+        if (unit) {
+          units.push(unit);
+        }
+      } catch {
+        // Not valid JSON, return as plain text
+        units.push({
+          type: 'stdout',
+          content: this.buffer,
+          timestamp: new Date().toISOString()
+        });
+      }
+    }
+
+    this.buffer = '';
+    return units;
+  }
+
+  /**
+   * Map parsed JSON object to appropriate IR type
+   * Handles various JSON event formats from different CLI tools:
+   * - Gemini CLI: stream-json format (init, message, result)
+   * - Codex CLI: --json format (thread.started, item.completed, turn.completed)
+   * - Claude CLI: stream-json format (system, assistant, result)
+   * - OpenCode CLI: --format json (step_start, text, step_finish)
+   */
+  private mapJsonToIR(json: any, fallbackStreamType: 'stdout' | 'stderr'): CliOutputUnit | null {
+    // Handle numeric timestamp (milliseconds) from OpenCode
+    const timestamp = typeof json.timestamp === 'number'
+      ? new Date(json.timestamp).toISOString()
+      : (json.timestamp || new Date().toISOString());
+
+    // ========== Gemini CLI stream-json format ==========
+    // {"type":"init","timestamp":"...","session_id":"...","model":"..."}
+    // {"type":"message","timestamp":"...","role":"assistant","content":"...","delta":true}
+    // {"type":"result","timestamp":"...","status":"success","stats":{...}}
+    if (json.type === 'init' && json.session_id) {
+      return {
+        type: 'metadata',
+        content: {
+          tool: 'gemini',
+          sessionId: json.session_id,
+          model: json.model,
+          raw: json
+        },
+        timestamp
+      };
+    }
+
+    if (json.type === 'message' && json.role) {
+      // Gemini assistant/user message
+      if (json.role === 'assistant') {
+        return {
+          type: 'stdout',
+          content: json.content || '',
+          timestamp
+        };
+      }
+      // Skip user messages in output (they're echo of input)
+      return null;
+    }
+
+    if (json.type === 'result' && json.stats) {
+      return {
+        type: 'metadata',
+        content: {
+          tool: 'gemini',
+          status: json.status,
+          stats: json.stats,
+          raw: json
+        },
+        timestamp
+      };
+    }
+
+    // Gemini tool_use: {"type":"tool_use","timestamp":"...","tool_name":"...","tool_id":"...","parameters":{...}}
+    if (json.type === 'tool_use' && json.tool_name) {
+      return {
+        type: 'tool_call',
+        content: {
+          tool: 'gemini',
+          action: 'invoke',
+          toolName: json.tool_name,
+          toolId: json.tool_id,
+          parameters: json.parameters,
+          raw: json
+        },
+        timestamp
+      };
+    }
+
+    // Gemini tool_result: {"type":"tool_result","timestamp":"...","tool_id":"...","status":"...","output":"..."}
+    if (json.type === 'tool_result' && json.tool_id) {
+      return {
+        type: 'tool_call',
+        content: {
+          tool: 'gemini',
+          action: 'result',
+          toolId: json.tool_id,
+          status: json.status,
+          output: json.output,
+          raw: json
+        },
+        timestamp
+      };
+    }
+
+    // ========== Codex CLI --json format ==========
+    // {"type":"thread.started","thread_id":"..."}
+    // {"type":"turn.started"}
+    // {"type":"item.started","item":{"id":"...","type":"command_execution","status":"in_progress"}}
+    // {"type":"item.completed","item":{"id":"...","type":"reasoning","text":"..."}}
+    // {"type":"item.completed","item":{"id":"...","type":"agent_message","text":"..."}}
+    // {"type":"item.completed","item":{"id":"...","type":"command_execution","aggregated_output":"..."}}
+    // {"type":"turn.completed","usage":{"input_tokens":...,"output_tokens":...}}
+    if (json.type === 'thread.started' && json.thread_id) {
+      return {
+        type: 'metadata',
+        content: {
+          tool: 'codex',
+          threadId: json.thread_id,
+          raw: json
+        },
+        timestamp
+      };
+    }
+
+    if (json.type === 'turn.started') {
+      return {
+        type: 'progress',
+        content: {
+          message: 'Turn started',
+          tool: 'codex'
+        },
+        timestamp
+      };
+    }
+
+    // Handle item.started - command execution in progress
+    if (json.type === 'item.started' && json.item) {
+      const item = json.item;
+      if (item.type === 'command_execution') {
+        return {
+          type: 'progress',
+          content: {
+            message: `Executing: ${item.command || 'command'}`,
+            tool: 'codex',
+            status: item.status || 'in_progress'
+          },
+          timestamp
+        };
+      }
+      // Other item.started types
+      return {
+        type: 'progress',
+        content: {
+          message: `Starting: ${item.type}`,
+          tool: 'codex'
+        },
+        timestamp
+      };
+    }
+
+    if (json.type === 'item.completed' && json.item) {
+      const item = json.item;
+
+      if (item.type === 'reasoning') {
+        return {
+          type: 'thought',
+          content: item.text || item.summary || '',
+          timestamp
+        };
+      }
+
+      if (item.type === 'agent_message') {
+        return {
+          type: 'stdout',
+          content: item.text || '',
+          timestamp
+        };
+      }
+
+      // Handle command_execution output
+      if (item.type === 'command_execution') {
+        // Show command output as code block
+        const output = item.aggregated_output || '';
+        return {
+          type: 'code',
+          content: {
+            command: item.command,
+            output: output,
+            exitCode: item.exit_code,
+            status: item.status
+          },
+          timestamp
+        };
+      }
+
+      // Other item types (function_call, etc.)
+      return {
+        type: 'system',
+        content: {
+          itemType: item.type,
+          itemId: item.id,
+          raw: item
+        },
+        timestamp
+      };
+    }
+
+    if (json.type === 'turn.completed' && json.usage) {
+      return {
+        type: 'metadata',
+        content: {
+          tool: 'codex',
+          usage: json.usage,
+          raw: json
+        },
+        timestamp
+      };
+    }
+
+    // ========== Claude CLI stream-json format ==========
+    // {"type":"system","subtype":"init","cwd":"...","session_id":"...","tools":[...],"model":"..."}
+    // {"type":"assistant","message":{...},"session_id":"..."}
+    // {"type":"result","subtype":"success","duration_ms":...,"result":"...","total_cost_usd":...}
+    if (json.type === 'system' && json.subtype === 'init') {
+      return {
+        type: 'metadata',
+        content: {
+          tool: 'claude',
+          sessionId: json.session_id,
+          model: json.model,
+          cwd: json.cwd,
+          tools: json.tools,
+          mcpServers: json.mcp_servers,
+          raw: json
+        },
+        timestamp
+      };
+    }
+
+    if (json.type === 'assistant' && json.message) {
+      // Extract text content from Claude message
+      const message = json.message;
+      const textContent = message.content
+        ?.filter((c: any) => c.type === 'text')
+        .map((c: any) => c.text)
+        .join('\n') || '';
+
+      return {
+        type: 'stdout',
+        content: textContent,
+        timestamp
+      };
+    }
+
+    if (json.type === 'result' && json.subtype) {
+      return {
+        type: 'metadata',
+        content: {
+          tool: 'claude',
+          status: json.subtype,
+          result: json.result,
+          durationMs: json.duration_ms,
+          totalCostUsd: json.total_cost_usd,
+          usage: json.usage,
+          modelUsage: json.modelUsage,
+          raw: json
+        },
+        timestamp
+      };
+    }
+
+    // ========== OpenCode CLI --format json ==========
+    // {"type":"step_start","timestamp":...,"sessionID":"...","part":{...}}
+    // {"type":"text","timestamp":...,"sessionID":"...","part":{"type":"text","text":"..."}}
+    // {"type":"tool_use","timestamp":...,"sessionID":"...","part":{"type":"tool","tool":"glob","input":{...},"state":{...}}}
+    // {"type":"step_finish","timestamp":...,"part":{"tokens":{...}}}
+    if (json.type === 'step_start' && json.sessionID) {
+      return {
+        type: 'progress',
+        content: {
+          message: 'Step started',
+          tool: 'opencode',
+          sessionId: json.sessionID
+        },
+        timestamp
+      };
+    }
+
+    if (json.type === 'text' && json.part) {
+      return {
+        type: 'stdout',
+        content: json.part.text || '',
+        timestamp
+      };
+    }
+
+    // OpenCode tool_use: {"type":"tool_use","part":{"type":"tool","tool":"glob","input":{...},"state":{"status":"..."}}}
+    if (json.type === 'tool_use' && json.part) {
+      const part = json.part;
+      const toolName = part.tool || 'unknown';
+      const status = part.state?.status || 'in_progress';
+      const input = part.input || {};
+
+      return {
+        type: 'tool_call',
+        content: {
+          tool: 'opencode',
+          action: status === 'completed' ? 'result' : 'invoke',
+          toolName: toolName,
+          toolId: part.callID || part.id,
+          parameters: input,
+          status: status,
+          output: part.output
+        },
+        timestamp
+      };
+    }
+
+    if (json.type === 'step_finish' && json.part) {
+      const tokens = json.part.tokens || {};
+      const inputTokens = tokens.input || 0;
+      const outputTokens = tokens.output || 0;
+
+      return {
+        type: 'metadata',
+        content: {
+          tool: 'opencode',
+          reason: json.part.reason,
+          tokens: { input: inputTokens, output: outputTokens },
+          cost: json.part.cost
+        },
+        timestamp
+      };
+    }
+
+    // ========== Legacy/Generic formats ==========
+    // Check for generic type field patterns
+    if (json.type) {
+      switch (json.type) {
+        case 'thought':
+        case 'thinking':
+        case 'reasoning':
+          return {
+            type: 'thought',
+            content: json.content || json.text || json.message,
+            timestamp
+          };
+
+        case 'code':
+        case 'code_block':
+          return {
+            type: 'code',
+            content: json.content || json.code,
+            timestamp
+          };
+
+        case 'diff':
+        case 'file_diff':
+        case 'file_change':
+          return {
+            type: 'file_diff',
+            content: {
+              path: json.path || json.file,
+              diff: json.diff || json.content,
+              action: json.action || 'modify'
+            },
+            timestamp
+          };
+
+        case 'progress':
+        case 'status':
+          return {
+            type: 'progress',
+            content: {
+              message: json.message || json.content,
+              progress: json.progress,
+              total: json.total
+            },
+            timestamp
+          };
+
+        case 'metadata':
+        case 'session_meta':
+          return {
+            type: 'metadata',
+            content: json.payload || json.data || json,
+            timestamp
+          };
+
+        case 'system':
+        case 'event':
+          return {
+            type: 'system',
+            content: json.message || json.content || json,
+            timestamp
+          };
+      }
+    }
+
+    // Check for legacy Codex JSONL format (response_item)
+    if (json.type === 'response_item' && json.payload) {
+      const payloadType = json.payload.type;
+
+      if (payloadType === 'message') {
+        // User or assistant message
+        const content = json.payload.content
+          ?.map((c: any) => c.text || '')
+          .filter((t: string) => t)
+          .join('\n') || '';
+
+        return {
+          type: 'stdout',
+          content,
+          timestamp
+        };
+      }
+
+      if (payloadType === 'reasoning') {
+        return {
+          type: 'thought',
+          content: json.payload.summary || json.payload.content,
+          timestamp
+        };
+      }
+
+      if (payloadType === 'function_call' || payloadType === 'function_call_output') {
+        return {
+          type: 'system',
+          content: json.payload,
+          timestamp
+        };
+      }
+    }
+
+    // Check for Gemini/Qwen message format (role-based)
+    if (json.role === 'user' || json.role === 'assistant') {
+      return {
+        type: 'stdout',
+        content: json.content || json.text || '',
+        timestamp
+      };
+    }
+
+    // Check for thoughts array
+    if (json.thoughts && Array.isArray(json.thoughts)) {
+      return {
+        type: 'thought',
+        content: json.thoughts.map((t: any) =>
+          typeof t === 'string' ? t : `${t.subject}: ${t.description}`
+        ).join('\n'),
+        timestamp
+      };
+    }
+
+    // Default: treat as stdout/stderr based on fallback
+    if (json.content || json.message || json.text) {
+      return {
+        type: fallbackStreamType,
+        content: json.content || json.message || json.text,
+        timestamp
+      };
+    }
+
+    // Unrecognized structure, return as metadata
+    return {
+      type: 'metadata',
+      content: json,
+      timestamp
+    };
+  }
+}
+
+// ========== Smart Content Formatter ==========
+
+/**
+ * Intelligent content formatter that detects and formats JSON content
+ * based on structural patterns rather than hardcoded tool-specific formats.
+ *
+ * Key detection patterns:
+ * - Session/Metadata: session_id, sessionID, thread_id, model, stats
+ * - Tool Calls: tool_name, tool, function_name, parameters
+ * - Progress: status, progress, state, reason
+ * - Tokens: tokens, usage, input_tokens, output_tokens
+ * - Text Content: content, text, message
+ */
+export class SmartContentFormatter {
+  /**
+   * Format structured content into human-readable text
+   * NEVER returns null - always returns displayable content to prevent data loss
+   */
+  static format(content: any, type: CliOutputUnitType): string {
+    // Handle null/undefined
+    if (content === null || content === undefined) {
+      return '';
+    }
+
+    // String content - return as-is
+    if (typeof content === 'string') {
+      return content;
+    }
+
+    // Primitive types - convert to string
+    if (typeof content !== 'object') {
+      return String(content);
+    }
+
+    // Type-specific formatting with fallback chain
+    let result: string | null = null;
+
+    switch (type) {
+      case 'metadata':
+        result = this.formatMetadata(content);
+        break;
+      case 'progress':
+        result = this.formatProgress(content);
+        break;
+      case 'tool_call':
+        result = this.formatToolCall(content);
+        break;
+      case 'code':
+        result = this.formatCode(content);
+        break;
+      case 'file_diff':
+        result = this.formatFileDiff(content);
+        break;
+      case 'thought':
+        result = this.formatThought(content);
+        break;
+      case 'system':
+        result = this.formatSystem(content);
+        break;
+      default:
+        // Try to extract text content from common fields
+        result = this.extractTextContent(content);
+    }
+
+    // If type-specific formatting succeeded, return it
+    if (result && result.trim()) {
+      return result;
+    }
+
+    // Fallback: try to extract any text content regardless of type
+    const textContent = this.extractTextContent(content);
+    if (textContent && textContent.trim()) {
+      return textContent;
+    }
+
+    // Last resort: format as readable JSON with type hint
+    return this.formatAsReadableJson(content, type);
+  }
+
+  /**
+   * Format object as readable JSON with type hint (fallback for unknown content)
+   * Ensures content is never lost
+   */
+  private static formatAsReadableJson(content: any, type: CliOutputUnitType): string {
+    try {
+      const jsonStr = JSON.stringify(content, null, 0);
+      // For short content, show inline; for long content, indicate it's data
+      if (jsonStr.length <= 200) {
+        return `[${type}] ${jsonStr}`;
+      }
+      // For long content, show truncated with type indicator
+      return `[${type}] ${jsonStr.substring(0, 200)}...`;
+    } catch {
+      // If JSON.stringify fails, try to extract keys
+      const keys = Object.keys(content).slice(0, 5).join(', ');
+      return `[${type}] {${keys}${Object.keys(content).length > 5 ? ', ...' : ''}}`;
+    }
+  }
+
+  /**
+   * Format metadata (session info, stats, etc.)
+   * Returns null if no meaningful metadata could be extracted
+   */
+  private static formatMetadata(content: any): string | null {
+    const parts: string[] = [];
+
+    // Tool identifier
+    if (content.tool) {
+      parts.push(`[${content.tool.toUpperCase()}]`);
+    }
+
+    // Session ID
+    const sessionId = content.sessionId || content.session_id || content.threadId || content.thread_id;
+    if (sessionId) {
+      parts.push(`Session: ${this.truncate(sessionId, 20)}`);
+    }
+
+    // Model info
+    if (content.model) {
+      parts.push(`Model: ${content.model}`);
+    }
+
+    // Status
+    if (content.status) {
+      parts.push(`Status: ${content.status}`);
+    }
+
+    // Reason (for step_finish events)
+    if (content.reason) {
+      parts.push(`Reason: ${content.reason}`);
+    }
+
+    // Duration
+    if (content.durationMs || content.duration_ms) {
+      const ms = content.durationMs || content.duration_ms;
+      parts.push(`Duration: ${this.formatDuration(ms)}`);
+    }
+
+    // Token usage
+    const tokens = this.extractTokens(content);
+    if (tokens) {
+      parts.push(`Tokens: ${tokens}`);
+    }
+
+    // Cost
+    if (content.totalCostUsd !== undefined || content.total_cost_usd !== undefined || content.cost !== undefined) {
+      const cost = content.totalCostUsd ?? content.total_cost_usd ?? content.cost;
+      parts.push(`Cost: $${typeof cost === 'number' ? cost.toFixed(6) : cost}`);
+    }
+
+    // Result
+    if (content.result && typeof content.result === 'string') {
+      parts.push(`Result: ${this.truncate(content.result, 100)}`);
+    }
+
+    // Return null if no meaningful parts extracted (let fallback handle it)
+    return parts.length > 0 ? parts.join(' | ') : null;
+  }
+
+  /**
+   * Format progress updates
+   * Returns null if no meaningful progress info could be extracted
+   */
+  private static formatProgress(content: any): string | null {
+    const parts: string[] = [];
+
+    // Tool identifier
+    if (content.tool) {
+      parts.push(`[${content.tool.toUpperCase()}]`);
+    }
+
+    // Message
+    if (content.message) {
+      parts.push(content.message);
+    }
+
+    // Status
+    if (content.status) {
+      parts.push(`(${content.status})`);
+    }
+
+    // Progress indicator
+    if (content.progress !== undefined && content.total !== undefined) {
+      parts.push(`[${content.progress}/${content.total}]`);
+    }
+
+    // Session ID (brief) - only show if no message (avoid duplication)
+    const sessionId = content.sessionId || content.session_id;
+    if (sessionId && !content.message) {
+      parts.push(`Session: ${this.truncate(sessionId, 12)}`);
+    }
+
+    // Return null if no meaningful parts extracted (let fallback handle it)
+    return parts.length > 0 ? parts.join(' ') : null;
+  }
+
+  /**
+   * Format tool call (invoke/result)
+   */
+  private static formatToolCall(content: any): string {
+    const toolName = content.toolName || content.tool_name || content.name || 'unknown';
+    const action = content.action || 'invoke';
+    const status = content.status;
+
+    if (action === 'result') {
+      const statusText = status || 'completed';
+      let result = `[Tool Result] ${toolName}: ${statusText}`;
+      if (content.output) {
+        const outputStr = typeof content.output === 'string' ? content.output : JSON.stringify(content.output);
+        result += ` → ${this.truncate(outputStr, 150)}`;
+      }
+      return result;
+    } else {
+      // invoke
+      let params = '';
+      if (content.parameters) {
+        const paramStr = typeof content.parameters === 'string'
+          ? content.parameters
+          : JSON.stringify(content.parameters);
+        params = this.truncate(paramStr, 100);
+      }
+      return `[Tool] ${toolName}(${params})`;
+    }
+  }
+
+  /**
+   * Format code block
+   */
+  private static formatCode(content: any): string {
+    if (typeof content === 'string') {
+      return `\`\`\`\n${content}\n\`\`\``;
+    }
+
+    const lang = content.language || '';
+    const code = content.code || content.output || content.content || '';
+    const command = content.command;
+
+    let result = '';
+    if (command) {
+      result += `$ ${command}\n`;
+    }
+    result += `\`\`\`${lang}\n${code}\n\`\`\``;
+
+    if (content.exitCode !== undefined) {
+      result += `\n(exit: ${content.exitCode})`;
+    }
+
+    return result;
+  }
+
+  /**
+   * Format file diff
+   */
+  private static formatFileDiff(content: any): string {
+    const path = content.path || content.file || 'unknown';
+    const action = content.action || 'modify';
+    const diff = content.diff || content.content || '';
+
+    return `[${action.toUpperCase()}] ${path}\n\`\`\`diff\n${diff}\n\`\`\``;
+  }
+
+  /**
+   * Format thought/reasoning
+   * Returns null if no text content could be extracted
+   */
+  private static formatThought(content: any): string | null {
+    if (typeof content === 'string') {
+      return `💭 ${content}`;
+    }
+    const text = content.text || content.summary || content.content || content.thinking;
+    return text ? `💭 ${text}` : null;
+  }
+
+  /**
+   * Format system message
+   * Returns null if no message content could be extracted
+   */
+  private static formatSystem(content: any): string | null {
+    if (typeof content === 'string') {
+      return `⚙️ ${content}`;
+    }
+    const message = content.message || content.content || content.event || content.info;
+    return message ? `⚙️ ${message}` : null;
+  }
+
+  /**
+   * Extract text content from common fields
+   */
+  private static extractTextContent(content: any): string | null {
+    // Priority order for text extraction
+    const textFields = ['text', 'content', 'message', 'output', 'data'];
+
+    for (const field of textFields) {
+      if (content[field] && typeof content[field] === 'string') {
+        return content[field];
+      }
+    }
+
+    // Check for nested content
+    if (content.part && typeof content.part === 'object') {
+      const nested = this.extractTextContent(content.part);
+      if (nested) return nested;
+    }
+
+    // Check for item content (Codex format)
+    if (content.item && typeof content.item === 'object') {
+      const nested = this.extractTextContent(content.item);
+      if (nested) return nested;
+    }
+
+    return null;
+  }
+
+  /**
+   * Extract token usage from various formats
+   */
+  private static extractTokens(content: any): string | null {
+    // Direct tokens object
+    if (content.tokens && typeof content.tokens === 'object') {
+      const input = content.tokens.input || content.tokens.input_tokens || 0;
+      const output = content.tokens.output || content.tokens.output_tokens || 0;
+      return `${input}↓ ${output}↑`;
+    }
+
+    // Usage object
+    if (content.usage && typeof content.usage === 'object') {
+      const input = content.usage.input_tokens || content.usage.inputTokens || 0;
+      const output = content.usage.output_tokens || content.usage.outputTokens || 0;
+      return `${input}↓ ${output}↑`;
+    }
+
+    // Stats object
+    if (content.stats && typeof content.stats === 'object') {
+      const input = content.stats.input_tokens || content.stats.inputTokens || 0;
+      const output = content.stats.output_tokens || content.stats.outputTokens || 0;
+      if (input || output) {
+        return `${input}↓ ${output}↑`;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Truncate string to max length
+   */
+  private static truncate(str: string, maxLen: number): string {
+    if (!str || str.length <= maxLen) return str;
+    return str.substring(0, maxLen) + '...';
+  }
+
+  /**
+   * Format duration from milliseconds
+   */
+  private static formatDuration(ms: number): string {
+    if (ms < 1000) return `${ms}ms`;
+    const s = Math.floor(ms / 1000);
+    if (s < 60) return `${s}s`;
+    const m = Math.floor(s / 60);
+    const rs = s % 60;
+    return `${m}m ${rs}s`;
+  }
+}
+
+// ========== Factory Function ==========
+
+/**
+ * Create an output parser instance based on format
+ * @param format - Output format type
+ * @returns Parser instance
+ */
+export function createOutputParser(format: 'text' | 'json-lines'): IOutputParser {
+  switch (format) {
+    case 'json-lines':
+      return new JsonLinesParser();
+    case 'text':
+    default:
+      return new PlainTextParser();
+  }
+}
+
+// ========== Utility Functions ==========
+
+/**
+ * Flatten output units into plain text string
+ * Useful for Resume scenario where we need concatenated context
+ *
+ * @param units - Array of output units to flatten
+ * @param options - Filtering and formatting options
+ * @returns Concatenated text content
+ */
+export function flattenOutputUnits(
+  units: CliOutputUnit[],
+  options?: {
+    includeTypes?: CliOutputUnitType[];
+    excludeTypes?: CliOutputUnitType[];
+    includeTimestamps?: boolean;
+    separator?: string;
+  }
+): string {
+  const {
+    includeTypes,
+    excludeTypes,
+    includeTimestamps = false,
+    separator = '\n'
+  } = options || {};
+
+  // Filter units by type
+  let filtered = units;
+  if (includeTypes && includeTypes.length > 0) {
+    filtered = filtered.filter(u => includeTypes.includes(u.type));
+  }
+  if (excludeTypes && excludeTypes.length > 0) {
+    filtered = filtered.filter(u => !excludeTypes.includes(u.type));
+  }
+
+  // Convert to text
+  const lines = filtered.map(unit => {
+    let text = '';
+
+    if (includeTimestamps) {
+      text += `[${unit.timestamp}] `;
+    }
+
+    // Extract text content based on type
+    if (typeof unit.content === 'string') {
+      text += unit.content;
+    } else if (typeof unit.content === 'object' && unit.content !== null) {
+      // Handle structured content with type-specific formatting
+      switch (unit.type) {
+        case 'file_diff':
+          // Format file diff with path and diff content
+          text += `File: ${unit.content.path}\n\`\`\`diff\n${unit.content.diff}\n\`\`\``;
+          break;
+
+        case 'code':
+          // Format code block with language
+          const lang = unit.content.language || '';
+          const code = unit.content.code || unit.content;
+          text += `\`\`\`${lang}\n${typeof code === 'string' ? code : JSON.stringify(code)}\n\`\`\``;
+          break;
+
+        case 'thought':
+          // Format thought/reasoning content
+          text += `[Thought] ${typeof unit.content === 'string' ? unit.content : JSON.stringify(unit.content)}`;
+          break;
+
+        case 'progress':
+          // Format progress updates
+          if (unit.content.message) {
+            text += unit.content.message;
+            if (unit.content.progress !== undefined && unit.content.total !== undefined) {
+              text += ` (${unit.content.progress}/${unit.content.total})`;
+            }
+          } else {
+            text += JSON.stringify(unit.content);
+          }
+          break;
+
+        case 'tool_call':
+          // Format tool call/result
+          if (unit.content.action === 'invoke') {
+            const params = unit.content.parameters ? JSON.stringify(unit.content.parameters) : '';
+            text += `[Tool] ${unit.content.toolName}(${params})`;
+          } else if (unit.content.action === 'result') {
+            const status = unit.content.status || 'unknown';
+            const output = unit.content.output ? `: ${unit.content.output.substring(0, 200)}${unit.content.output.length > 200 ? '...' : ''}` : '';
+            text += `[Tool Result] ${status}${output}`;
+          } else {
+            text += JSON.stringify(unit.content);
+          }
+          break;
+
+        case 'metadata':
+        case 'system':
+          // Metadata and system events are typically excluded from prompt context
+          // Include minimal representation if they passed filtering
+          text += JSON.stringify(unit.content);
+          break;
+
+        default:
+          // Fallback for unknown structured types
+          text += JSON.stringify(unit.content);
+      }
+    } else {
+      text += String(unit.content);
+    }
+
+    return text;
+  });
+
+  return lines.join(separator);
+}
+
+/**
+ * Extract specific content type from units
+ * Convenience helper for common extraction patterns
+ */
+export function extractContent(
+  units: CliOutputUnit[],
+  type: CliOutputUnitType
+): string[] {
+  return units
+    .filter(u => u.type === type)
+    .map(u => typeof u.content === 'string' ? u.content : JSON.stringify(u.content));
+}
+
+/**
+ * Get statistics about output units
+ * Useful for debugging and analytics
+ */
+export function getOutputStats(units: CliOutputUnit[]): {
+  total: number;
+  byType: Record<CliOutputUnitType, number>;
+  firstTimestamp?: string;
+  lastTimestamp?: string;
+} {
+  const byType: Record<string, number> = {};
+  let firstTimestamp: string | undefined;
+  let lastTimestamp: string | undefined;
+
+  for (const unit of units) {
+    byType[unit.type] = (byType[unit.type] || 0) + 1;
+
+    if (!firstTimestamp || unit.timestamp < firstTimestamp) {
+      firstTimestamp = unit.timestamp;
+    }
+    if (!lastTimestamp || unit.timestamp > lastTimestamp) {
+      lastTimestamp = unit.timestamp;
+    }
+  }
+
+  return {
+    total: units.length,
+    byType: byType as Record<CliOutputUnitType, number>,
+    firstTimestamp,
+    lastTimestamp
+  };
+}