claude-agent-sdk 0.34.0 → 0.36.0

data/lib/claude_agent_sdk/types.rb

@@ -157,8 +157,178 @@ module ClaudeAgentSDK
     end
     private_class_method :option_hash_key
 
+    # Bounded, human-oriented #inspect listing the non-nil instance variables
+    # in definition order:
+    #
+    #   #<ClaudeAgentSDK::ResultMessage subtype="success" num_turns=3 ...>
+    #
+    # Messages carry whole transcripts, tool payloads and usage maps, so the
+    # output is bounded rather than faithful: long Strings are truncated,
+    # long Arrays/Hashes abbreviated, and nesting past INSPECT_MAX_DEPTH (or
+    # a reference cycle) collapses to a placeholder. Other objects keep their
+    # own #inspect (truncated) unless they only have Kernel#inspect, which
+    # dumps every ivar recursively — those (SDK MCP server instances, store
+    # adapters, observers) show as `#<ClassName>`. For display only: nothing
+    # sent to the CLI goes through #inspect or #to_s (wire output uses #to_h).
+    def inspect
+      inspect_with(0, {}.compare_by_identity)
+    end
+
+    # Object#to_s ignores instance variables, so `puts message` would print
+    # only a class name and an address. Types with a natural textual form
+    # (UserMessage, AssistantMessage, TextBlock, ResultMessage, SystemMessage)
+    # override this.
+    def to_s
+      inspect
+    end
+
+    # Declares attributes that carry credentials (env vars, auth headers).
+    # Objects get logged, so #inspect shows them filtered; #to_h and
+    # everything sent to the CLI are unaffected. Inherited by subclasses.
+    def self.inspect_filtered(*names)
+      @inspect_filtered_attributes = (inspect_filtered_attributes + names.map(&:to_s)).uniq.freeze
+    end
+
+    def self.inspect_filtered_attributes
+      @inspect_filtered_attributes || (superclass <= Type ? superclass.inspect_filtered_attributes : [].freeze)
+    end
+
+    INSPECT_MAX_STRING = 80
+    INSPECT_MAX_ITEMS = 5
+    INSPECT_MAX_DEPTH = 2
+    private_constant :INSPECT_MAX_STRING, :INSPECT_MAX_ITEMS, :INSPECT_MAX_DEPTH
+
+    protected
+
+    # `seen` holds the Types/containers on the current rendering path (not
+    # every one rendered so far), so a shared-but-acyclic value still renders
+    # in full wherever it appears.
+    def inspect_with(depth, seen)
+      return "#<#{inspect_class_name} …>" if depth > INSPECT_MAX_DEPTH || seen.key?(self)
+
+      seen[self] = true
+      begin
+        attributes = inspect_attributes.map do |name, value|
+          " #{name}=#{inspect_bounded(value, depth + 1, seen)}"
+        end
+        "#<#{inspect_class_name}#{attributes.join}>"
+      ensure
+        seen.delete(self)
+      end
+    end
+
     private
 
+    # [name, value] pairs rendered by #inspect. Subclasses override to hide
+    # redundant state or redact secrets — never by mutating the object.
+    def inspect_attributes
+      filtered = self.class.inspect_filtered_attributes
+      instance_variables.filter_map do |ivar|
+        value = instance_variable_get(ivar)
+        next if value.nil?
+
+        name = ivar.to_s.delete_prefix('@')
+        [name, filtered.include?(name) ? inspect_filter(value) : value]
+      end
+    end
+
+    # A credential-bearing Hash keeps its keys (useful when debugging which
+    # variables are set) with every value replaced; anything else is replaced
+    # outright. Builds a new Hash; the object itself is never touched.
+    def inspect_filter(value)
+      value.respond_to?(:each_key) ? value.each_key.to_h { |key| [key, '[FILTERED]'] } : '[FILTERED]'
+    end
+
+    def inspect_class_name
+      self.class.name || self.class.inspect
+    end
+
+    def inspect_bounded(value, depth, seen)
+      case value
+      when Type then value.inspect_with(depth, seen)
+      when String then inspect_truncated(value)
+      when Array then inspect_container(value, '[', ']', depth, seen) { |item| inspect_bounded(item, depth + 1, seen) }
+      when Hash
+        inspect_container(value, '{', '}', depth, seen) do |key, item|
+          "#{inspect_hash_key(key, depth + 1, seen)}#{inspect_bounded(item, depth + 1, seen)}"
+        end
+      when Proc, Method, UnboundMethod then inspect_callable(value)
+      else inspect_leaf(value)
+      end
+    end
+
+    def inspect_container(value, open, close, depth, seen, &)
+      return "#{open}#{close}" if value.empty?
+      return "#{open}…(#{value.size})#{close}" if depth > INSPECT_MAX_DEPTH || seen.key?(value)
+
+      seen[value] = true
+      begin
+        parts = value.first(INSPECT_MAX_ITEMS).map(&)
+        parts << "…(+#{value.size - INSPECT_MAX_ITEMS} more)" if value.size > INSPECT_MAX_ITEMS
+        "#{open}#{parts.join(', ')}#{close}"
+      ensure
+        seen.delete(value)
+      end
+    end
+
+    # Rendered by hand rather than via Hash#inspect, whose format differs
+    # between Ruby 3.3 (`{:a=>1}`) and 3.4 (`{a: 1}`).
+    def inspect_hash_key(key, depth, seen)
+      return "#{key.name}: " if key.is_a?(Symbol) && key.inspect.match?(/\A:\w+[?!]?\z/)
+
+      "#{inspect_bounded(key, depth, seen)} => "
+    end
+
+    def inspect_truncated(string)
+      return string.inspect if string.length <= INSPECT_MAX_STRING
+
+      "#{string[0, INSPECT_MAX_STRING].inspect}…(+#{string.length - INSPECT_MAX_STRING} chars)"
+    end
+
+    # Callbacks (can_use_tool, hooks, callback_wrapper, ...) are user-supplied:
+    # render them from source_location rather than their own #inspect, which
+    # a subclass may override (and raise from) and which embeds an absolute
+    # path — `#<Proc(lambda) permissions.rb:17>`, `#<Method Policy#call>`.
+    def inspect_callable(value)
+      label = if value.is_a?(Proc)
+                value.lambda? ? 'Proc(lambda)' : 'Proc'
+              else
+                "#{value.class.name} #{value.owner.name || value.owner.inspect}##{value.name}"
+              end
+      file, line = value.source_location
+      rendered = file ? "#<#{label} #{File.basename(file)}:#{line}>" : "#<#{label}>"
+      inspect_truncated_text(rendered)
+    rescue StandardError
+      inspect_leaf(value)
+    end
+
+    def inspect_truncated_text(rendered)
+      return rendered if rendered.length <= INSPECT_MAX_STRING
+
+      "#{rendered[0, INSPECT_MAX_STRING]}…(+#{rendered.length - INSPECT_MAX_STRING} chars)"
+    end
+
+    # Printing must never raise (it runs inside loggers and `puts`), so an
+    # object whose #inspect raises, or a BasicObject without one, falls back
+    # to a placeholder.
+    def inspect_leaf(value)
+      return "#<#{value.class}>" if kernel_inspect_only?(value)
+
+      inspect_truncated_text(value.inspect)
+    rescue StandardError
+      begin
+        "#<#{value.class}>"
+      rescue StandardError
+        '#<?>'
+      end
+    end
+
+    def kernel_inspect_only?(value)
+      Kernel.instance_method(:method).bind_call(value, :inspect).owner == Kernel
+    rescue TypeError # not a Kernel object: BasicObject, Delegator
+      false
+    end
+
     # Allow camelCase attribute access
     def method_missing(method_name, ...)
       normalized = normalize_name(method_name)
@@ -230,6 +400,10 @@ module ClaudeAgentSDK
   # Text content block
   class TextBlock < Type
     attr_accessor :text
+
+    def to_s
+      text.to_s
+    end
   end
 
   # Thinking content block
@@ -375,6 +549,22 @@ module ClaudeAgentSDK
       super
       @data ||= attributes if attributes.is_a?(Hash)
     end
+
+    def to_s
+      subtype.nil? ? '[system]' : "[system: #{subtype}]"
+    end
+
+    private
+
+    # A typed subclass (InitMessage, TaskStartedMessage, ...) already exposes
+    # the fields of its raw frame as attributes; repeating @data would double
+    # the output. A bare SystemMessage (unrecognized subtype) keeps it, since
+    # @data is the only place its payload lives.
+    def inspect_attributes
+      return super if instance_of?(SystemMessage)
+
+      super.reject { |pair| pair.first == 'data' }
+    end
   end
 
   # Init system message (emitted at session start and after /clear)
@@ -755,6 +945,19 @@ module ClaudeAgentSDK
     # @return [Hash{Symbol => Object}, nil]
     # @see UserMessage#origin
     attr_accessor :origin
+
+    # One human-readable line, e.g. `[result: success, 3 turns, 4.2s, $0.0120]`
+    # (parts the CLI did not report are left out). An error result appends its
+    # `errors`. Use #inspect for every field.
+    def to_s
+      parts = [subtype].compact
+      parts << "#{num_turns} #{num_turns == 1 ? 'turn' : 'turns'}" unless num_turns.nil?
+      parts << format('%.1fs', duration_ms / 1000.0) if duration_ms.is_a?(Numeric)
+      parts << format('$%.4f', total_cost_usd) if total_cost_usd.is_a?(Numeric)
+      line = parts.empty? ? '[result]' : "[result: #{parts.join(', ')}]"
+      line += " - #{Array(errors).join('; ')}" if is_error && !Array(errors).empty?
+      line
+    end
   end
 
   # Stream event for partial message updates
@@ -1723,6 +1926,8 @@ module ClaudeAgentSDK
     attr_accessor :command, :args, :env
     attr_reader :type
 
+    inspect_filtered :env
+
     def initialize(attributes = {})
       super
       @type = 'stdio'
@@ -1742,6 +1947,8 @@ module ClaudeAgentSDK
     attr_accessor :url, :headers
     attr_reader :type
 
+    inspect_filtered :headers
+
     def initialize(attributes = {})
       super
       @type = 'sse'
@@ -1760,6 +1967,8 @@ module ClaudeAgentSDK
     attr_accessor :url, :headers
     attr_reader :type
 
+    inspect_filtered :headers
+
     def initialize(attributes = {})
       super
       @type = 'http'
@@ -1980,6 +2189,9 @@ module ClaudeAgentSDK
 
   # Claude Agent Options for configuring queries
   class ClaudeAgentOptions < Type
+    # `env` routinely carries credentials (ANTHROPIC_API_KEY, ...).
+    inspect_filtered :env
+
     attr_accessor :allowed_tools, :system_prompt, :mcp_servers, :permission_mode,
                   :resume, :resume_session_at, :session_id, :max_turns, :disallowed_tools,
                   :model, :permission_prompt_tool_name, :cwd, :cli_path, :settings,
@@ -2226,13 +2438,17 @@ module ClaudeAgentSDK
     # A callable receiving a zero-arg invocation; it MUST call it and
     # return its value:
     #
-    #   callback_wrapper: ->(invocation) { Rails.application.executor.wrap { invocation.call } }
+    #   callback_wrapper: ->(invocation) { MyApm.trace('agent.callback') { invocation.call } }
     #
     # The wrapper runs on the same execution context as the callback —
-    # inside the worker thread in :thread mode (so executor.wrap checks AR
-    # connections back in when the callback ends), in place on the reactor
+    # inside the worker thread in :thread mode, in place on the reactor
     # fiber in :inline mode. Exceptions propagate through it unchanged; it
     # must not swallow them. Default nil (no wrapping).
+    #
+    # Rails apps: use ClaudeAgentSDK::Railtie.callback_wrapper, which runs
+    # callbacks in the Rails executor (AR connections check back in when the
+    # callback ends). A bare `Rails.application.executor.wrap` deadlocks
+    # under development code reloading in :thread mode.
     def callback_wrapper=(value)
       raise ArgumentError, "callback_wrapper must be a callable or nil (got #{value.inspect})" unless value.nil? || value.respond_to?(:call)
 

data/lib/claude_agent_sdk/version.rb

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