claude-agent-sdk 0.15.1 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a037f9cca486fc8d6e94269b9f5f7b686574665ff403457761db764f9f50f07
-  data.tar.gz: 01bff518e3306d1fb23b8bc1e9b11b72785a98aecf3636a1096c5522f4720444
+  metadata.gz: 9c6e7dfb9b25404169db87bff2a8688c9bd1103bb04ebc980bd8206091b33f87
+  data.tar.gz: 1c921d464b1b8272742f8de36800635e5f777fb88a42304ac9a5a1d7f9027beb
 SHA512:
-  metadata.gz: 253df532bcdc4a6e0b13e0d4438944bcf9c6018b5d1062b4831efc6dac7a332c1759f85137e6de4fc44de0e8b1eb7ccfd0033698392c8faf6ca40f7e237b2e51
-  data.tar.gz: 143d4ee8780d1a675e1531edc944de1756bff03faa9c42513b9672a3f37ac670dc17929a936cf0f1520d1cfdc45c53042d8f8fa07ad5a559e4b59439e79848f5
+  metadata.gz: 5b7b2c4e0503db55b36d761bec12bdc43619e16688a3b3e38c79d50a34af92d68e6ccea29e523eaaa0279f577a296cb25ba0c447cafb388c2127bc870b3cc703
+  data.tar.gz: bd05dac1831ce8b77462019f026f88b2618ca6df4be31bc84c86c145fbc59fb54738530a8b6f188c654d588171acfe28efd216a8c12b846d4d3e5ae1cfe2d37f

data/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.16.0] - 2026-04-22
+
+### Added
+- **`#text` on every message type that carries content.** No more hand-rolling a `select { TextBlock }.map(&:text).join` in every consumer.
+  - `AssistantMessage#text` — joins text across `TextBlock`s in the content array.
+  - `UserMessage#text` — handles both String content (plain prompt) and Array-of-blocks content.
+  - `SessionMessage#text` — joins text across parsed content blocks from a historical transcript.
+  - `#to_s` on each message type is aliased to `#text`, so `puts message` and string interpolation just work.
+  - Non-text blocks (`ToolUseBlock`, `ThinkingBlock`, `ToolResultBlock`, `UnknownBlock`) intentionally do **not** answer `#text` — only `TextBlock` is textual. The message helpers use `Array#grep(TextBlock)` to select text blocks.
+- **`SessionMessage#content_blocks`** returns typed block objects (`TextBlock`, `ThinkingBlock`, `ToolUseBlock`, `ToolResultBlock`, `UnknownBlock`) instead of the raw hash blocks from the JSONL transcript. Unknown block types become `UnknownBlock` for forward compatibility with newer CLI versions.
+
+### Changed
+- Rails Integration / Quick Start / Observability / File Checkpointing README examples dropped the `content.select { is_a?(TextBlock) }.map(&:text).join` dance in favor of `message.text`.
+
 ## [0.15.1] - 2026-04-22
 
 ### Fixed

data/README.md

@@ -106,7 +106,7 @@ Add this line to your application's Gemfile:
 gem 'claude-agent-sdk', github: 'ya-luotao/claude-agent-sdk-ruby'
 
 # Or use a stable version from RubyGems
-gem 'claude-agent-sdk', '~> 0.15.1'
+gem 'claude-agent-sdk', '~> 0.16.0'
 ```
 
 And then execute:
@@ -159,11 +159,7 @@ require 'claude_agent_sdk'
 
 # Simple query
 ClaudeAgentSDK.query(prompt: "Hello Claude") do |message|
-  if message.is_a?(ClaudeAgentSDK::AssistantMessage)
-    message.content.each do |block|
-      puts block.text if block.is_a?(ClaudeAgentSDK::TextBlock)
-    end
-  end
+  puts message.text if message.is_a?(ClaudeAgentSDK::AssistantMessage)
 end
 
 # With options
@@ -260,11 +256,10 @@ Async do
 
     # Receive the response
     client.receive_response do |msg|
-      if msg.is_a?(ClaudeAgentSDK::AssistantMessage)
-        msg.content.each do |block|
-          puts block.text if block.is_a?(ClaudeAgentSDK::TextBlock)
-        end
-      elsif msg.is_a?(ClaudeAgentSDK::ResultMessage)
+      case msg
+      when ClaudeAgentSDK::AssistantMessage
+        puts msg.text
+      when ClaudeAgentSDK::ResultMessage
         puts "Cost: $#{msg.total_cost_usd}" if msg.total_cost_usd
       end
     end
@@ -928,10 +923,7 @@ Async do
       # Capture UUID for rewind capability
       user_message_uuids << message.uuid if message.uuid
     when ClaudeAgentSDK::AssistantMessage
-      # Handle assistant responses
-      message.content.each do |block|
-        puts block.text if block.is_a?(ClaudeAgentSDK::TextBlock)
-      end
+      puts message.text
     when ClaudeAgentSDK::ResultMessage
       puts "Query completed (cost: $#{message.total_cost_usd})"
     end
@@ -1140,11 +1132,7 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
 )
 
 ClaudeAgentSDK.query(prompt: "List files in /tmp", options: options) do |msg|
-  if msg.is_a?(ClaudeAgentSDK::AssistantMessage)
-    msg.content.each do |block|
-      puts block.text if block.is_a?(ClaudeAgentSDK::TextBlock)
-    end
-  end
+  puts msg.text if msg.is_a?(ClaudeAgentSDK::AssistantMessage)
 end
 
 # For long-running apps, flush before exit:
@@ -1258,8 +1246,7 @@ class ChatAgentJob < ApplicationJob
         client.receive_response do |message|
           case message
           when ClaudeAgentSDK::AssistantMessage
-            text = extract_text(message)
-            ChatChannel.broadcast_to(chat_id, { type: 'chunk', content: text })
+            ChatChannel.broadcast_to(chat_id, { type: 'chunk', content: message.text })
 
           when ClaudeAgentSDK::ResultMessage
             ChatChannel.broadcast_to(chat_id, {
@@ -1274,15 +1261,6 @@ class ChatAgentJob < ApplicationJob
       end
     end.wait
   end
-
-  private
-
-  def extract_text(message)
-    message.content
-      .select { |b| b.is_a?(ClaudeAgentSDK::TextBlock) }
-      .map(&:text)
-      .join("\n\n")
-  end
 end
 ```
 

data/lib/claude_agent_sdk/message_parser.rb

@@ -288,24 +288,32 @@ module ClaudeAgentSDK
       )
     end
 
+    # Accepts blocks with either symbol or string keys — live CLI messages
+    # arrive symbol-keyed (parsed via `symbolize_names: true`), session
+    # transcripts arrive string-keyed (parsed via `symbolize_names: false`).
+    # Uses a nil-aware fallback so `is_error: false` survives.
     def self.parse_content_block(block)
-      case block[:type]
+      get = lambda do |key|
+        v = block[key]
+        v.nil? ? block[key.to_s] : v
+      end
+      case get.call(:type)
       when 'text'
-        TextBlock.new(text: block[:text])
+        TextBlock.new(text: get.call(:text))
       when 'thinking'
-        ThinkingBlock.new(thinking: block[:thinking], signature: block[:signature])
+        ThinkingBlock.new(thinking: get.call(:thinking), signature: get.call(:signature))
       when 'tool_use'
-        ToolUseBlock.new(id: block[:id], name: block[:name], input: block[:input])
+        ToolUseBlock.new(id: get.call(:id), name: get.call(:name), input: get.call(:input))
       when 'tool_result'
         ToolResultBlock.new(
-          tool_use_id: block[:tool_use_id],
-          content: block[:content],
-          is_error: block[:is_error]
+          tool_use_id: get.call(:tool_use_id),
+          content: get.call(:content),
+          is_error: get.call(:is_error)
         )
       else
         # Forward-compatible: preserve unrecognized content block types (e.g., "document", "image")
         # so newer CLI versions don't crash older SDK versions.
-        UnknownBlock.new(type: block[:type], data: block)
+        UnknownBlock.new(type: get.call(:type), data: block)
       end
     end
   end

data/lib/claude_agent_sdk/sessions.rb

@@ -38,6 +38,36 @@ module ClaudeAgentSDK
       @message = message
       @parent_tool_use_id = parent_tool_use_id
     end
+
+    # Concatenated text across every TextBlock in this message.
+    # Returns "" when the message has no text content (nil message,
+    # non-Hash message, empty content, or only non-text blocks).
+    def text
+      raw = @message.is_a?(Hash) ? (@message['content'] || @message[:content]) : nil
+      case raw
+      when String then raw
+      when Array  then content_blocks.grep(TextBlock).map(&:text).join("\n\n")
+      else ''
+      end
+    end
+
+    alias to_s text
+
+    # Typed content blocks for this message. Each entry is one of
+    # TextBlock, ThinkingBlock, ToolUseBlock, ToolResultBlock, or
+    # UnknownBlock (for forward-compatibility with newer CLI block types).
+    # Returns [] when the message has no array-of-blocks content (nil
+    # message, non-Hash message, String content, missing content).
+    def content_blocks
+      return [] unless @message.is_a?(Hash)
+
+      raw = @message['content'] || @message[:content]
+      return [] unless raw.is_a?(Array)
+
+      raw.filter_map do |block|
+        MessageParser.parse_content_block(block) if block.is_a?(Hash)
+      end
+    end
   end
 
   # Session browsing functions

data/lib/claude_agent_sdk/types.rb

@@ -123,6 +123,19 @@ module ClaudeAgentSDK
       @parent_tool_use_id = parent_tool_use_id
       @tool_use_result = tool_use_result # Tool result data when message is a tool response
     end
+
+    # Concatenated text of this message. Handles both String content
+    # (plain-text user prompt) and Array-of-blocks content (typed content).
+    # Returns "" when there is no text.
+    def text
+      case @content
+      when String then @content
+      when Array then @content.grep(TextBlock).map(&:text).join("\n\n")
+      else ''
+      end
+    end
+
+    alias to_s text
   end
 
   # Assistant message with content blocks
@@ -142,6 +155,14 @@ module ClaudeAgentSDK
       @session_id = session_id # Session the message belongs to
       @uuid = uuid # Unique message UUID in the session transcript
     end
+
+    # Concatenated text across every TextBlock in this message's content.
+    # Returns "" when the message has no text (e.g., a pure tool_use turn).
+    def text
+      Array(@content).grep(TextBlock).map(&:text).join("\n\n")
+    end
+
+    alias to_s text
   end
 
   # System message with metadata

data/lib/claude_agent_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeAgentSDK
-  VERSION = '0.15.1'
+  VERSION = '0.16.0'
 end

data/lib/claude_agent_sdk.rb

@@ -71,11 +71,7 @@ module ClaudeAgentSDK
   #     permission_mode: 'acceptEdits'
   #   )
   #   ClaudeAgentSDK.query(prompt: "Create a hello.rb file", options: options) do |msg|
-  #     if msg.is_a?(ClaudeAgentSDK::AssistantMessage)
-  #       msg.content.each do |block|
-  #         puts block.text if block.is_a?(ClaudeAgentSDK::TextBlock)
-  #       end
-  #     end
+  #     puts msg.text if msg.is_a?(ClaudeAgentSDK::AssistantMessage)
   #   end
   #
   # @example Streaming input

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.15.1
+  version: 0.16.0
 platform: ruby
 authors:
 - Community Contributors