claude_agent 0.7.7 → 0.7.9

data/lib/claude_agent/message_parser.rb

@@ -3,6 +3,10 @@
 module ClaudeAgent
   # Parses raw JSON messages from the CLI into typed message objects
   #
+  # Uses a registry to route messages by type (and subtype for system messages)
+  # to named parse methods. New message types can be added with a single
+  # {.register} call instead of modifying case statements.
+  #
   # @example
   #   parser = MessageParser.new
   #   message = parser.parse({"type" => "assistant", "message" => {...}})
@@ -13,93 +17,94 @@ module ClaudeAgent
       @logger = logger
     end
 
+    # Registry of parser methods keyed by routing string.
+    # Keys are "type" for top-level types, "type:subtype" for system subtypes.
+    @registry = {}
+
+    class << self
+      attr_reader :registry
+
+      # Register a parse method for a message type
+      #
+      # @param key [String] Routing key ("type" or "type:subtype")
+      # @param method_name [Symbol] Name of the private parse method
+      def register(key, method_name)
+        @registry[key] = method_name
+      end
+    end
+
     # Parse a raw message hash into a typed message object
     #
-    # @param raw [Hash] Raw message from CLI
+    # @param raw [Hash] Raw message from CLI (string or symbol keys, camelCase or snake_case)
     # @return [UserMessage, UserMessageReplay, AssistantMessage, SystemMessage, ResultMessage, StreamEvent, CompactBoundaryMessage, StatusMessage, ToolProgressMessage, HookResponseMessage, AuthStatusMessage, TaskNotificationMessage, HookStartedMessage, HookProgressMessage, ToolUseSummaryMessage, FilesPersistedEvent, TaskStartedMessage, RateLimitEvent, PromptSuggestionMessage]
     # @raise [MessageParseError] If message cannot be parsed
     def parse(raw)
-      type = raw["type"]
+      raw = raw.deep_transform_keys { |key| key.to_s.underscore.to_sym }
+      type = raw[:type]
       logger.debug("parser") { "Parsing message: #{type}" }
 
-      case type
-      when "user"
-        parse_user_message(raw)
-      when "assistant"
-        parse_assistant_message(raw)
-      when "system"
-        # Check for special system subtypes
-        case raw["subtype"]
-        when "compact_boundary"
-          parse_compact_boundary_message(raw)
-        when "status"
-          parse_status_message(raw)
-        when "hook_response"
-          parse_hook_response_message(raw)
-        when "task_notification"
-          parse_task_notification_message(raw)
-        when "hook_started"
-          parse_hook_started_message(raw)
-        when "hook_progress"
-          parse_hook_progress_message(raw)
-        when "files_persisted"
-          parse_files_persisted_event(raw)
-        when "task_started"
-          parse_task_started_message(raw)
-        else
-          parse_system_message(raw)
-        end
-      when "result"
-        parse_result_message(raw)
-      when "stream_event"
-        parse_stream_event(raw)
-      when "tool_progress"
-        parse_tool_progress_message(raw)
-      when "auth_status"
-        parse_auth_status_message(raw)
-      when "tool_use_summary"
-        parse_tool_use_summary_message(raw)
-      when "rate_limit_event"
-        parse_rate_limit_event(raw)
-      when "prompt_suggestion"
-        parse_prompt_suggestion_message(raw)
+      # Look up parser: try specific system subtype first, then top-level type
+      method_name = if type == "system" && raw[:subtype]
+        self.class.registry["system:#{raw[:subtype]}"] || self.class.registry["system"]
       else
-        logger.error("parser") { "Unknown message type: #{type}" }
-        raise MessageParseError.new("Unknown message type: #{type}", raw_message: raw)
+        self.class.registry[type]
+      end
+
+      if method_name
+        send(method_name, raw)
+      else
+        logger.warn("parser") { "Unknown message type: #{type}, wrapping in GenericMessage" }
+        GenericMessage.new(message_type: type.to_s, raw: raw)
       end
     end
 
+    # --- Parser Registration ---
+    #
+    # Top-level message types
+
+    register "user",              :parse_user_message
+    register "assistant",         :parse_assistant_message
+    register "result",            :parse_result_message
+    register "stream_event",      :parse_stream_event
+    register "tool_progress",     :parse_tool_progress_message
+    register "auth_status",       :parse_auth_status_message
+    register "tool_use_summary",  :parse_tool_use_summary_message
+    register "rate_limit_event",  :parse_rate_limit_event
+    register "prompt_suggestion", :parse_prompt_suggestion_message
+
+    # System message subtypes
+
+    register "system",                   :parse_system_message             # fallback for unknown subtypes
+    register "system:compact_boundary",  :parse_compact_boundary_message
+    register "system:status",            :parse_status_message
+    register "system:hook_response",     :parse_hook_response_message
+    register "system:task_notification", :parse_task_notification_message
+    register "system:hook_started",      :parse_hook_started_message
+    register "system:hook_progress",     :parse_hook_progress_message
+    register "system:files_persisted",   :parse_files_persisted_event
+    register "system:task_started",      :parse_task_started_message
+    register "system:task_progress",     :parse_task_progress_message
+
     private
 
     def logger
       @logger || ClaudeAgent.logger
     end
 
-    # Fetch a value from a hash, trying both snake_case and camelCase keys
-    # @param raw [Hash] The hash to fetch from
-    # @param snake_key [Symbol, String] The snake_case key to try
-    # @param default [Object] Default value if neither key exists
-    # @return [Object] The value or default
-    def fetch_dual(raw, snake_key, default = nil)
-      snake_str = snake_key.to_s
-      camel_str = snake_str.camelize(:lower)
-      raw[snake_str] || raw[camel_str] || default
-    end
-
     def parse_user_message(raw)
-      message = raw["message"] || {}
-      content = parse_user_content(message["content"])
+      message = raw[:message] || {}
+      content = parse_user_content(message[:content])
 
-      is_replay = fetch_dual(raw, :is_replay)
-      is_synthetic = fetch_dual(raw, :is_synthetic)
-      tool_use_result = fetch_dual(raw, :tool_use_result)
+      is_replay = raw[:is_replay]
+      is_synthetic = raw[:is_synthetic]
+      tool_use_result = raw[:tool_use_result]
 
       if is_replay
         UserMessageReplay.new(
           content: content,
-          uuid: raw["uuid"],
-          session_id: fetch_dual(raw, :session_id),
-          parent_tool_use_id: raw["parent_tool_use_id"],
+          uuid: raw[:uuid],
+          session_id: raw[:session_id],
+          parent_tool_use_id: raw[:parent_tool_use_id],
           is_replay: true,
           is_synthetic: is_synthetic,
           tool_use_result: tool_use_result
@@ -107,61 +112,61 @@ module ClaudeAgent
       else
         UserMessage.new(
           content: content,
-          uuid: raw["uuid"],
-          session_id: fetch_dual(raw, :session_id),
-          parent_tool_use_id: raw["parent_tool_use_id"]
+          uuid: raw[:uuid],
+          session_id: raw[:session_id],
+          parent_tool_use_id: raw[:parent_tool_use_id]
         )
       end
     end
 
     def parse_assistant_message(raw)
-      message = raw["message"] || {}
-      content_raw = message["content"] || []
+      message = raw[:message] || {}
+      content_raw = message[:content] || []
       content = content_raw.map { |block| parse_content_block(block) }
 
       AssistantMessage.new(
         content: content,
-        model: message["model"] || raw["model"] || "unknown",
-        uuid: raw["uuid"],
-        session_id: fetch_dual(raw, :session_id),
-        error: message["error"] || raw["error"],
-        parent_tool_use_id: raw["parent_tool_use_id"]
+        model: message[:model] || raw[:model] || "unknown",
+        uuid: raw[:uuid],
+        session_id: raw[:session_id],
+        error: message[:error] || raw[:error],
+        parent_tool_use_id: raw[:parent_tool_use_id]
       )
     end
 
     def parse_system_message(raw)
       SystemMessage.new(
-        subtype: raw["subtype"] || "unknown",
-        data: raw["data"] || raw
+        subtype: raw[:subtype] || "unknown",
+        data: raw[:data] || raw
       )
     end
 
     def parse_compact_boundary_message(raw)
       CompactBoundaryMessage.new(
-        uuid: raw["uuid"] || "",
-        session_id: fetch_dual(raw, :session_id, ""),
-        compact_metadata: fetch_dual(raw, :compact_metadata, {})
+        uuid: raw[:uuid] || "",
+        session_id: raw[:session_id] || "",
+        compact_metadata: raw[:compact_metadata] || {}
       )
     end
 
     def parse_result_message(raw)
-      permission_denials = parse_permission_denials(fetch_dual(raw, :permission_denials))
+      permission_denials = parse_permission_denials(raw[:permission_denials])
 
       ResultMessage.new(
-        subtype: raw["subtype"] || "unknown",
-        duration_ms: fetch_dual(raw, :duration_ms, 0),
-        duration_api_ms: fetch_dual(raw, :duration_api_ms, 0),
-        is_error: fetch_dual(raw, :is_error, false),
-        num_turns: fetch_dual(raw, :num_turns, 0),
-        session_id: fetch_dual(raw, :session_id, ""),
-        total_cost_usd: fetch_dual(raw, :total_cost_usd),
-        usage: raw["usage"],
-        result: raw["result"],
-        structured_output: fetch_dual(raw, :structured_output),
-        errors: raw["errors"],
+        subtype: raw[:subtype] || "unknown",
+        duration_ms: raw[:duration_ms] || 0,
+        duration_api_ms: raw[:duration_api_ms] || 0,
+        is_error: raw[:is_error] || false,
+        num_turns: raw[:num_turns] || 0,
+        session_id: raw[:session_id] || "",
+        total_cost_usd: raw[:total_cost_usd],
+        usage: raw[:usage],
+        result: raw[:result],
+        structured_output: raw[:structured_output],
+        errors: raw[:errors],
         permission_denials: permission_denials,
-        model_usage: fetch_dual(raw, :model_usage),
-        stop_reason: fetch_dual(raw, :stop_reason)
+        model_usage: raw[:model_usage],
+        stop_reason: raw[:stop_reason]
       )
     end
 
@@ -170,19 +175,19 @@ module ClaudeAgent
 
       denials.map do |denial|
         SDKPermissionDenial.new(
-          tool_name: fetch_dual(denial, :tool_name),
-          tool_use_id: fetch_dual(denial, :tool_use_id),
-          tool_input: fetch_dual(denial, :tool_input)
+          tool_name: denial[:tool_name],
+          tool_use_id: denial[:tool_use_id],
+          tool_input: denial[:tool_input]
         )
       end
     end
 
     def parse_stream_event(raw)
       StreamEvent.new(
-        uuid: raw["uuid"] || "",
-        session_id: fetch_dual(raw, :session_id, ""),
-        event: raw["event"] || {},
-        parent_tool_use_id: raw["parent_tool_use_id"]
+        uuid: raw[:uuid] || "",
+        session_id: raw[:session_id] || "",
+        event: raw[:event] || {},
+        parent_tool_use_id: raw[:parent_tool_use_id]
       )
     end
 
@@ -200,173 +205,184 @@ module ClaudeAgent
     def parse_content_block(block)
       return block unless block.is_a?(Hash)
 
-      type = block["type"]
+      type = block[:type]
 
       case type
       when "text"
-        TextBlock.new(text: block["text"] || "")
+        TextBlock.new(text: block[:text] || "")
       when "thinking"
         ThinkingBlock.new(
-          thinking: block["thinking"] || "",
-          signature: block["signature"] || ""
+          thinking: block[:thinking] || "",
+          signature: block[:signature] || ""
         )
       when "tool_use"
         ToolUseBlock.new(
-          id: block["id"] || "",
-          name: block["name"] || "",
-          input: block["input"] || {}
+          id: block[:id] || "",
+          name: block[:name] || "",
+          input: block[:input] || {}
         )
       when "tool_result"
         ToolResultBlock.new(
-          tool_use_id: block["tool_use_id"] || "",
-          content: block["content"],
-          is_error: block["is_error"]
+          tool_use_id: block[:tool_use_id] || "",
+          content: block[:content],
+          is_error: block[:is_error]
         )
       when "server_tool_use"
         ServerToolUseBlock.new(
-          id: block["id"] || "",
-          name: block["name"] || "",
-          input: block["input"] || {},
-          server_name: block["server_name"] || ""
+          id: block[:id] || "",
+          name: block[:name] || "",
+          input: block[:input] || {},
+          server_name: block[:server_name] || ""
         )
       when "server_tool_result"
         ServerToolResultBlock.new(
-          tool_use_id: block["tool_use_id"] || "",
-          content: block["content"],
-          is_error: block["is_error"],
-          server_name: block["server_name"] || ""
+          tool_use_id: block[:tool_use_id] || "",
+          content: block[:content],
+          is_error: block[:is_error],
+          server_name: block[:server_name] || ""
         )
       when "image"
         ImageContentBlock.new(
-          source: block["source"] || {}
+          source: block[:source] || {}
         )
       else
-        # Return raw hash for unknown block types
-        block
+        GenericBlock.new(block_type: type.to_s, raw: block)
       end
     end
 
     def parse_status_message(raw)
       StatusMessage.new(
-        uuid: raw["uuid"] || "",
-        session_id: fetch_dual(raw, :session_id, ""),
-        status: raw["status"]
+        uuid: raw[:uuid] || "",
+        session_id: raw[:session_id] || "",
+        status: raw[:status]
       )
     end
 
     def parse_tool_progress_message(raw)
       ToolProgressMessage.new(
-        uuid: raw["uuid"] || "",
-        session_id: fetch_dual(raw, :session_id, ""),
-        tool_use_id: fetch_dual(raw, :tool_use_id, ""),
-        tool_name: fetch_dual(raw, :tool_name, ""),
-        parent_tool_use_id: fetch_dual(raw, :parent_tool_use_id),
-        elapsed_time_seconds: fetch_dual(raw, :elapsed_time_seconds, 0)
+        uuid: raw[:uuid] || "",
+        session_id: raw[:session_id] || "",
+        tool_use_id: raw[:tool_use_id] || "",
+        tool_name: raw[:tool_name] || "",
+        parent_tool_use_id: raw[:parent_tool_use_id],
+        elapsed_time_seconds: raw[:elapsed_time_seconds] || 0
       )
     end
 
     def parse_hook_response_message(raw)
       HookResponseMessage.new(
-        uuid: raw["uuid"] || "",
-        session_id: fetch_dual(raw, :session_id, ""),
-        hook_id: fetch_dual(raw, :hook_id),
-        hook_name: fetch_dual(raw, :hook_name, ""),
-        hook_event: fetch_dual(raw, :hook_event, ""),
-        stdout: raw["stdout"] || "",
-        stderr: raw["stderr"] || "",
-        output: raw["output"] || "",
-        exit_code: fetch_dual(raw, :exit_code),
-        outcome: raw["outcome"]
+        uuid: raw[:uuid] || "",
+        session_id: raw[:session_id] || "",
+        hook_id: raw[:hook_id],
+        hook_name: raw[:hook_name] || "",
+        hook_event: raw[:hook_event] || "",
+        stdout: raw[:stdout] || "",
+        stderr: raw[:stderr] || "",
+        output: raw[:output] || "",
+        exit_code: raw[:exit_code],
+        outcome: raw[:outcome]
       )
     end
 
     def parse_auth_status_message(raw)
       AuthStatusMessage.new(
-        uuid: raw["uuid"] || "",
-        session_id: fetch_dual(raw, :session_id, ""),
-        is_authenticating: fetch_dual(raw, :is_authenticating, false),
-        output: raw["output"] || [],
-        error: raw["error"]
+        uuid: raw[:uuid] || "",
+        session_id: raw[:session_id] || "",
+        is_authenticating: raw[:is_authenticating] || false,
+        output: raw[:output] || [],
+        error: raw[:error]
       )
     end
 
     def parse_task_notification_message(raw)
       TaskNotificationMessage.new(
-        uuid: raw["uuid"] || "",
-        session_id: fetch_dual(raw, :session_id, ""),
-        task_id: fetch_dual(raw, :task_id, ""),
-        status: raw["status"] || "unknown",
-        output_file: fetch_dual(raw, :output_file, ""),
-        summary: raw["summary"] || ""
+        uuid: raw[:uuid] || "",
+        session_id: raw[:session_id] || "",
+        task_id: raw[:task_id] || "",
+        status: raw[:status] || "unknown",
+        output_file: raw[:output_file] || "",
+        summary: raw[:summary] || ""
       )
     end
 
     def parse_hook_started_message(raw)
       HookStartedMessage.new(
-        uuid: raw["uuid"] || "",
-        session_id: fetch_dual(raw, :session_id, ""),
-        hook_id: fetch_dual(raw, :hook_id, ""),
-        hook_name: fetch_dual(raw, :hook_name, ""),
-        hook_event: fetch_dual(raw, :hook_event, "")
+        uuid: raw[:uuid] || "",
+        session_id: raw[:session_id] || "",
+        hook_id: raw[:hook_id] || "",
+        hook_name: raw[:hook_name] || "",
+        hook_event: raw[:hook_event] || ""
       )
     end
 
     def parse_hook_progress_message(raw)
       HookProgressMessage.new(
-        uuid: raw["uuid"] || "",
-        session_id: fetch_dual(raw, :session_id, ""),
-        hook_id: fetch_dual(raw, :hook_id, ""),
-        hook_name: fetch_dual(raw, :hook_name, ""),
-        hook_event: fetch_dual(raw, :hook_event, ""),
-        stdout: raw["stdout"] || "",
-        stderr: raw["stderr"] || "",
-        output: raw["output"] || ""
+        uuid: raw[:uuid] || "",
+        session_id: raw[:session_id] || "",
+        hook_id: raw[:hook_id] || "",
+        hook_name: raw[:hook_name] || "",
+        hook_event: raw[:hook_event] || "",
+        stdout: raw[:stdout] || "",
+        stderr: raw[:stderr] || "",
+        output: raw[:output] || ""
       )
     end
 
     def parse_tool_use_summary_message(raw)
       ToolUseSummaryMessage.new(
-        uuid: raw["uuid"] || "",
-        session_id: fetch_dual(raw, :session_id, ""),
-        summary: raw["summary"] || "",
-        preceding_tool_use_ids: fetch_dual(raw, :preceding_tool_use_ids, [])
+        uuid: raw[:uuid] || "",
+        session_id: raw[:session_id] || "",
+        summary: raw[:summary] || "",
+        preceding_tool_use_ids: raw[:preceding_tool_use_ids] || []
       )
     end
 
     def parse_files_persisted_event(raw)
       FilesPersistedEvent.new(
-        uuid: raw["uuid"] || "",
-        session_id: fetch_dual(raw, :session_id, ""),
-        files: raw["files"] || [],
-        failed: raw["failed"] || [],
-        processed_at: fetch_dual(raw, :processed_at)
+        uuid: raw[:uuid] || "",
+        session_id: raw[:session_id] || "",
+        files: raw[:files] || [],
+        failed: raw[:failed] || [],
+        processed_at: raw[:processed_at]
       )
     end
 
     def parse_task_started_message(raw)
       TaskStartedMessage.new(
-        uuid: raw["uuid"] || "",
-        session_id: fetch_dual(raw, :session_id, ""),
-        task_id: fetch_dual(raw, :task_id, ""),
-        tool_use_id: fetch_dual(raw, :tool_use_id),
-        description: raw["description"],
-        task_type: fetch_dual(raw, :task_type)
+        uuid: raw[:uuid] || "",
+        session_id: raw[:session_id] || "",
+        task_id: raw[:task_id] || "",
+        tool_use_id: raw[:tool_use_id],
+        description: raw[:description],
+        task_type: raw[:task_type]
+      )
+    end
+
+    def parse_task_progress_message(raw)
+      TaskProgressMessage.new(
+        uuid: raw[:uuid] || "",
+        session_id: raw[:session_id] || "",
+        task_id: raw[:task_id] || "",
+        tool_use_id: raw[:tool_use_id],
+        description: raw[:description] || "",
+        usage: raw[:usage],
+        last_tool_name: raw[:last_tool_name]
       )
     end
 
     def parse_rate_limit_event(raw)
       RateLimitEvent.new(
-        rate_limit_info: fetch_dual(raw, :rate_limit_info, {}),
-        uuid: raw["uuid"] || "",
-        session_id: fetch_dual(raw, :session_id, "")
+        rate_limit_info: raw[:rate_limit_info] || {},
+        uuid: raw[:uuid] || "",
+        session_id: raw[:session_id] || ""
       )
     end
 
     def parse_prompt_suggestion_message(raw)
       PromptSuggestionMessage.new(
-        uuid: raw["uuid"] || "",
-        session_id: fetch_dual(raw, :session_id, ""),
-        suggestion: raw["suggestion"] || ""
+        uuid: raw[:uuid] || "",
+        session_id: raw[:session_id] || "",
+        suggestion: raw[:suggestion] || ""
       )
     end
   end