claude_agent 0.1.0

data/lib/claude_agent/message_parser.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Parses raw JSON messages from the CLI into typed message objects
+  #
+  # @example
+  #   parser = MessageParser.new
+  #   message = parser.parse({"type" => "assistant", "message" => {...}})
+  #
+  class MessageParser
+    # Parse a raw message hash into a typed message object
+    #
+    # @param raw [Hash] Raw message from CLI
+    # @return [UserMessage, UserMessageReplay, AssistantMessage, SystemMessage, ResultMessage, StreamEvent, CompactBoundaryMessage, StatusMessage, ToolProgressMessage, HookResponseMessage, AuthStatusMessage]
+    # @raise [MessageParseError] If message cannot be parsed
+    def parse(raw)
+      type = raw["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)
+        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)
+      else
+        raise MessageParseError.new("Unknown message type: #{type}", raw_message: raw)
+      end
+    end
+
+    private
+
+    # 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"])
+
+      is_replay = fetch_dual(raw, :is_replay)
+      is_synthetic = fetch_dual(raw, :is_synthetic)
+      tool_use_result = fetch_dual(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"],
+          is_replay: true,
+          is_synthetic: is_synthetic,
+          tool_use_result: tool_use_result
+        )
+      else
+        UserMessage.new(
+          content: content,
+          uuid: raw["uuid"],
+          session_id: fetch_dual(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"] || []
+      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"]
+      )
+    end
+
+    def parse_system_message(raw)
+      SystemMessage.new(
+        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, {})
+      )
+    end
+
+    def parse_result_message(raw)
+      permission_denials = parse_permission_denials(fetch_dual(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"],
+        permission_denials: permission_denials,
+        model_usage: fetch_dual(raw, :model_usage)
+      )
+    end
+
+    def parse_permission_denials(denials)
+      return nil unless denials.is_a?(Array)
+
+      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)
+        )
+      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"]
+      )
+    end
+
+    def parse_user_content(content)
+      case content
+      when String
+        content
+      when Array
+        content.map { |block| parse_content_block(block) }
+      else
+        content.to_s
+      end
+    end
+
+    def parse_content_block(block)
+      return block unless block.is_a?(Hash)
+
+      type = block["type"]
+
+      case type
+      when "text"
+        TextBlock.new(text: block["text"] || "")
+      when "thinking"
+        ThinkingBlock.new(
+          thinking: block["thinking"] || "",
+          signature: block["signature"] || ""
+        )
+      when "tool_use"
+        ToolUseBlock.new(
+          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"]
+        )
+      when "server_tool_use"
+        ServerToolUseBlock.new(
+          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"] || ""
+        )
+      when "image"
+        ImageContentBlock.new(
+          source: block["source"] || {}
+        )
+      else
+        # Return raw hash for unknown block types
+        block
+      end
+    end
+
+    def parse_status_message(raw)
+      StatusMessage.new(
+        uuid: raw["uuid"] || "",
+        session_id: fetch_dual(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)
+      )
+    end
+
+    def parse_hook_response_message(raw)
+      HookResponseMessage.new(
+        uuid: raw["uuid"] || "",
+        session_id: fetch_dual(raw, :session_id, ""),
+        hook_name: fetch_dual(raw, :hook_name, ""),
+        hook_event: fetch_dual(raw, :hook_event, ""),
+        stdout: raw["stdout"] || "",
+        stderr: raw["stderr"] || "",
+        exit_code: fetch_dual(raw, :exit_code)
+      )
+    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"]
+      )
+    end
+  end
+end

data/lib/claude_agent/messages.rb

@@ -0,0 +1,421 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # User message sent to Claude
+  #
+  # @example
+  #   msg = UserMessage.new(content: "Hello!", uuid: "abc-123", session_id: "session-abc")
+  #
+  UserMessage = Data.define(:content, :uuid, :session_id, :parent_tool_use_id) do
+    def initialize(content:, uuid: nil, session_id: nil, parent_tool_use_id: nil)
+      super
+    end
+
+    def type
+      :user
+    end
+
+    # Get text content if content is a string
+    # @return [String, nil]
+    def text
+      content.is_a?(String) ? content : nil
+    end
+
+    # Check if this is a replayed message
+    # @return [Boolean]
+    def replay?
+      false
+    end
+  end
+
+  # User message replay (TypeScript SDK parity)
+  #
+  # Sent when resuming a session with existing conversation history.
+  # These messages represent replayed user messages from a previous session.
+  #
+  # @example
+  #   msg = UserMessageReplay.new(
+  #     content: "Hello!",
+  #     uuid: "abc-123",
+  #     session_id: "session-abc",
+  #     is_replay: true
+  #   )
+  #   msg.replay?  # => true
+  #
+  UserMessageReplay = Data.define(
+    :content,
+    :uuid,
+    :session_id,
+    :parent_tool_use_id,
+    :is_replay,
+    :is_synthetic,
+    :tool_use_result
+  ) do
+    def initialize(
+      content:,
+      uuid: nil,
+      session_id: nil,
+      parent_tool_use_id: nil,
+      is_replay: true,
+      is_synthetic: nil,
+      tool_use_result: nil
+    )
+      super
+    end
+
+    def type
+      :user
+    end
+
+    # Get text content if content is a string
+    # @return [String, nil]
+    def text
+      content.is_a?(String) ? content : nil
+    end
+
+    # Check if this is a replayed message
+    # @return [Boolean]
+    def replay?
+      is_replay == true
+    end
+
+    # Check if this is a synthetic message (system-generated)
+    # @return [Boolean]
+    def synthetic?
+      is_synthetic == true
+    end
+  end
+
+  # Assistant message from Claude
+  #
+  # @example
+  #   msg = AssistantMessage.new(
+  #     content: [TextBlock.new(text: "Hello!")],
+  #     model: "claude-sonnet-4-5-20250514",
+  #     uuid: "msg-123",
+  #     session_id: "session-abc"
+  #   )
+  #
+  AssistantMessage = Data.define(:content, :model, :uuid, :session_id, :error, :parent_tool_use_id) do
+    def initialize(content:, model:, uuid: nil, session_id: nil, error: nil, parent_tool_use_id: nil)
+      super
+    end
+
+    def type
+      :assistant
+    end
+
+    # Get all text content concatenated
+    # @return [String]
+    def text
+      content
+        .select { |block| block.is_a?(TextBlock) }
+        .map(&:text)
+        .join
+    end
+
+    # Get all thinking content concatenated
+    # @return [String]
+    def thinking
+      content
+        .select { |block| block.is_a?(ThinkingBlock) }
+        .map(&:thinking)
+        .join
+    end
+
+    # Get all tool use blocks
+    # @return [Array<ToolUseBlock>]
+    def tool_uses
+      content.select { |block| block.is_a?(ToolUseBlock) }
+    end
+
+    # Check if assistant wants to use a tool
+    # @return [Boolean]
+    def has_tool_use?
+      content.any? { |block| block.is_a?(ToolUseBlock) }
+    end
+  end
+
+  # System message (internal events)
+  #
+  # @example
+  #   msg = SystemMessage.new(subtype: "init", data: {version: "2.0.0"})
+  #
+  SystemMessage = Data.define(:subtype, :data) do
+    def type
+      :system
+    end
+  end
+
+  # Result message (final message with usage/cost info) - TypeScript SDK parity
+  #
+  # @example Success result
+  #   msg = ResultMessage.new(
+  #     subtype: "success",
+  #     duration_ms: 1500,
+  #     duration_api_ms: 1200,
+  #     is_error: false,
+  #     num_turns: 3,
+  #     session_id: "session-abc",
+  #     total_cost_usd: 0.05,
+  #     usage: {input_tokens: 100, output_tokens: 50}
+  #   )
+  #
+  # @example Error result
+  #   msg = ResultMessage.new(
+  #     subtype: "error_max_turns",
+  #     errors: ["Maximum turns exceeded"],
+  #     ...
+  #   )
+  #
+  ResultMessage = Data.define(
+    :subtype,
+    :duration_ms,
+    :duration_api_ms,
+    :is_error,
+    :num_turns,
+    :session_id,
+    :total_cost_usd,
+    :usage,
+    :result,
+    :structured_output,
+    :errors,             # Array<String> for error subtypes
+    :permission_denials, # Array<SDKPermissionDenial>
+    :model_usage         # Hash with per-model usage breakdown
+  ) do
+    def initialize(
+      subtype:,
+      duration_ms:,
+      duration_api_ms:,
+      is_error:,
+      num_turns:,
+      session_id:,
+      total_cost_usd: nil,
+      usage: nil,
+      result: nil,
+      structured_output: nil,
+      errors: nil,
+      permission_denials: nil,
+      model_usage: nil
+    )
+      super
+    end
+
+    def type
+      :result
+    end
+
+    # Check if this was an error result
+    # @return [Boolean]
+    def error?
+      is_error
+    end
+
+    # Check if this was a successful result
+    # @return [Boolean]
+    def success?
+      !is_error
+    end
+  end
+
+  # Stream event (partial message during streaming)
+  #
+  # @example
+  #   event = StreamEvent.new(
+  #     uuid: "evt-123",
+  #     session_id: "session-abc",
+  #     event: {type: "content_block_delta", delta: {type: "text_delta", text: "Hello"}}
+  #   )
+  #
+  StreamEvent = Data.define(:uuid, :session_id, :event, :parent_tool_use_id) do
+    def initialize(uuid:, session_id:, event:, parent_tool_use_id: nil)
+      super
+    end
+
+    def type
+      :stream_event
+    end
+
+    # Get the event type from the raw event
+    # @return [String, nil]
+    def event_type
+      event["type"]
+    end
+  end
+
+  # Compact boundary message (conversation compaction marker) - TypeScript SDK parity
+  #
+  # Sent when the conversation is compacted to reduce context size.
+  # Contains metadata about the compaction operation.
+  #
+  # @example
+  #   msg = CompactBoundaryMessage.new(
+  #     uuid: "msg-123",
+  #     session_id: "session-abc",
+  #     compact_metadata: { trigger: "auto", pre_tokens: 50000 }
+  #   )
+  #   msg.trigger     # => "auto"
+  #   msg.pre_tokens  # => 50000
+  #
+  CompactBoundaryMessage = Data.define(:uuid, :session_id, :compact_metadata) do
+    def type
+      :compact_boundary
+    end
+
+    # Get the compaction trigger type
+    # @return [String] "manual" or "auto"
+    def trigger
+      compact_metadata[:trigger] || compact_metadata["trigger"]
+    end
+
+    # Get the token count before compaction
+    # @return [Integer, nil]
+    def pre_tokens
+      compact_metadata[:pre_tokens] || compact_metadata["pre_tokens"]
+    end
+  end
+
+  # Status message (TypeScript SDK parity)
+  #
+  # Reports session status like 'compacting' during operations.
+  #
+  # @example
+  #   msg = StatusMessage.new(
+  #     uuid: "msg-123",
+  #     session_id: "session-abc",
+  #     status: "compacting"
+  #   )
+  #
+  StatusMessage = Data.define(:uuid, :session_id, :status) do
+    def type
+      :status
+    end
+  end
+
+  # Tool progress message (TypeScript SDK parity)
+  #
+  # Reports progress during long-running tool executions.
+  #
+  # @example
+  #   msg = ToolProgressMessage.new(
+  #     uuid: "msg-123",
+  #     session_id: "session-abc",
+  #     tool_use_id: "tool-456",
+  #     tool_name: "Bash",
+  #     elapsed_time_seconds: 5.2
+  #   )
+  #
+  ToolProgressMessage = Data.define(
+    :uuid,
+    :session_id,
+    :tool_use_id,
+    :tool_name,
+    :parent_tool_use_id,
+    :elapsed_time_seconds
+  ) do
+    def initialize(
+      uuid:,
+      session_id:,
+      tool_use_id:,
+      tool_name:,
+      elapsed_time_seconds:,
+      parent_tool_use_id: nil
+    )
+      super
+    end
+
+    def type
+      :tool_progress
+    end
+  end
+
+  # Hook response message (TypeScript SDK parity)
+  #
+  # Contains output from hook executions.
+  #
+  # @example
+  #   msg = HookResponseMessage.new(
+  #     uuid: "msg-123",
+  #     session_id: "session-abc",
+  #     hook_name: "my-hook",
+  #     hook_event: "PreToolUse",
+  #     stdout: "Hook output",
+  #     stderr: "",
+  #     exit_code: 0
+  #   )
+  #
+  HookResponseMessage = Data.define(
+    :uuid,
+    :session_id,
+    :hook_name,
+    :hook_event,
+    :stdout,
+    :stderr,
+    :exit_code
+  ) do
+    def initialize(
+      uuid:,
+      session_id:,
+      hook_name:,
+      hook_event:,
+      stdout: "",
+      stderr: "",
+      exit_code: nil
+    )
+      super
+    end
+
+    def type
+      :hook_response
+    end
+  end
+
+  # Auth status message (TypeScript SDK parity)
+  #
+  # Reports authentication status during login flows.
+  #
+  # @example
+  #   msg = AuthStatusMessage.new(
+  #     uuid: "msg-123",
+  #     session_id: "session-abc",
+  #     is_authenticating: true,
+  #     output: ["Waiting for browser..."]
+  #   )
+  #
+  AuthStatusMessage = Data.define(
+    :uuid,
+    :session_id,
+    :is_authenticating,
+    :output,
+    :error
+  ) do
+    def initialize(
+      uuid:,
+      session_id:,
+      is_authenticating:,
+      output: [],
+      error: nil
+    )
+      super
+    end
+
+    def type
+      :auth_status
+    end
+  end
+
+  # All message types
+  MESSAGE_TYPES = [
+    UserMessage,
+    UserMessageReplay,
+    AssistantMessage,
+    SystemMessage,
+    ResultMessage,
+    StreamEvent,
+    CompactBoundaryMessage,
+    StatusMessage,
+    ToolProgressMessage,
+    HookResponseMessage,
+    AuthStatusMessage
+  ].freeze
+end