claude_agent 0.7.8 → 0.7.10

data/lib/claude_agent/session_paths.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module ClaudeAgent
+  # Shared path/directory infrastructure for session discovery.
+  #
+  # Provides methods to locate Claude Code session files on disk,
+  # encode project directory paths, and resolve git worktrees.
+  # Used by both ListSessions and GetSessionMessages.
+  #
+  module SessionPaths
+    MAX_SLUG_LENGTH = 200
+    UUID_PATTERN = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
+
+    module_function
+
+    # @return [String] Claude config directory
+    def config_dir
+      (ENV["CLAUDE_CONFIG_DIR"] || File.join(Dir.home, ".claude"))
+    end
+
+    # @return [String] Projects directory within config
+    def projects_dir
+      File.join(config_dir, "projects")
+    end
+
+    # Get the expected project directory path for a given working directory.
+    #
+    # @param path [String] Working directory
+    # @return [String] Full path to project sessions directory
+    def project_dir_for(path)
+      File.join(projects_dir, encode_project_dir(path))
+    end
+
+    # Encode a project directory path to a slug for the projects directory.
+    # Matches the TypeScript SDK's q9 function exactly.
+    #
+    # @param path [String] Absolute directory path
+    # @return [String] Encoded slug
+    def encode_project_dir(path)
+      slug = path.gsub(/[^a-zA-Z0-9]/, "-")
+      return slug if slug.length <= MAX_SLUG_LENGTH
+
+      hash = java_string_hash(path)
+      "#{slug[0, MAX_SLUG_LENGTH]}-#{hash}"
+    end
+
+    # Java-style string hash (matches TypeScript DM function).
+    # Computes hash = ((hash << 5) - hash + charCode) as 32-bit signed integer,
+    # then returns absolute value in base 36.
+    #
+    # @param str [String]
+    # @return [String] Base-36 hash
+    def java_string_hash(str)
+      hash = 0
+      str.each_char do |c|
+        hash = ((hash << 5) - hash + c.ord) & 0xFFFFFFFF
+        # Convert to signed 32-bit integer
+        hash -= 0x100000000 if hash >= 0x80000000
+      end
+      hash.abs.to_s(36)
+    end
+
+    # Look up the project directory for a given path, handling hash suffix fallback.
+    # Matches TypeScript's tQ function.
+    #
+    # @param path [String] Working directory
+    # @return [String, nil] Project directory path or nil
+    def find_project_dir(path)
+      expected = project_dir_for(path)
+      return expected if File.directory?(expected)
+
+      # Try prefix matching for hash-suffixed directories
+      slug = encode_project_dir(path)
+      return nil if slug.length <= MAX_SLUG_LENGTH
+
+      prefix = slug[0, MAX_SLUG_LENGTH]
+      base = projects_dir
+      return nil unless File.directory?(base)
+
+      Dir.entries(base).each do |entry|
+        next if entry.start_with?(".")
+        next unless File.directory?(File.join(base, entry))
+        return File.join(base, entry) if entry.start_with?("#{prefix}-")
+      end
+
+      nil
+    end
+
+    # Resolve symlinks and normalize a path.
+    #
+    # @param path [String]
+    # @return [String]
+    def realpath(path)
+      File.realpath(path).unicode_normalize(:nfc)
+    rescue SystemCallError
+      path.unicode_normalize(:nfc)
+    end
+
+    # Get git worktree paths for a directory.
+    #
+    # @param dir [String] Working directory
+    # @return [Array<String>] Worktree paths
+    def git_worktrees(dir)
+      output = nil
+      IO.popen([ "git", "worktree", "list", "--porcelain" ], chdir: dir, err: File::NULL) do |io|
+        Timeout.timeout(5) { output = io.read }
+      end
+
+      return [] unless output
+
+      output.lines
+        .select { |line| line.start_with?("worktree ") }
+        .map { |line| line[9..].strip.unicode_normalize(:nfc) }
+    rescue SystemCallError, Timeout::Error, Errno::ENOENT
+      []
+    end
+  end
+end

data/lib/claude_agent/tool_activity.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # A single tool execution in the conversation timeline.
+  #
+  # Pairs a ToolUseBlock with its ToolResultBlock and adds context
+  # about which turn it occurred in and when.
+  #
+  # @example
+  #   conversation.tool_activity.each do |activity|
+  #     puts activity.display_label
+  #     puts "  Turn: #{activity.turn_index}"
+  #     puts "  Duration: #{activity.duration}s" if activity.duration
+  #     puts "  Error!" if activity.error?
+  #   end
+  #
+  ToolActivity = Data.define(
+    :tool_use,
+    :tool_result,
+    :turn_index,
+    :started_at,
+    :completed_at
+  ) do
+    def initialize(tool_use:, tool_result: nil, turn_index:, started_at: nil, completed_at: nil)
+      super
+    end
+
+    # Tool name
+    # @return [String]
+    def name
+      tool_use.name
+    end
+
+    # Human-readable label (delegates to ToolUseBlock#display_label)
+    # @return [String]
+    def display_label
+      tool_use.display_label
+    end
+
+    # Detailed summary (delegates to ToolUseBlock#summary)
+    # @param max [Integer] Maximum length
+    # @return [String]
+    def summary(max: 60)
+      tool_use.summary(max: max)
+    end
+
+    # File path if this is a file-based tool
+    # @return [String, nil]
+    def file_path
+      tool_use.file_path
+    end
+
+    # Tool use ID
+    # @return [String]
+    def id
+      tool_use.id
+    end
+
+    # Whether the tool produced an error result
+    # @return [Boolean]
+    def error?
+      tool_result&.is_error == true
+    end
+
+    # Whether the tool execution is complete (has a result)
+    # @return [Boolean]
+    def complete?
+      !tool_result.nil?
+    end
+
+    # Duration in seconds (nil if timing not available)
+    # @return [Float, nil]
+    def duration
+      return nil unless started_at && completed_at
+      completed_at - started_at
+    end
+  end
+end

data/lib/claude_agent/turn_result.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Represents a complete agent turn — everything from sending a prompt
+  # to receiving the final ResultMessage.
+  #
+  # Accumulates messages as they flow through and provides convenient
+  # accessors for text, tool use, usage data, and more. Eliminates the
+  # 5+ message type `case` statement that every app rewrites.
+  #
+  # @example Via Client
+  #   turn = client.send_and_receive("Fix the bug in auth.rb")
+  #   puts turn.text
+  #   puts "Cost: $#{turn.cost}"
+  #   puts "Tools used: #{turn.tool_uses.map(&:display_label).join(", ")}"
+  #
+  # @example With streaming block
+  #   turn = client.send_and_receive("Fix the bug") do |msg|
+  #     case msg
+  #     when ClaudeAgent::AssistantMessage
+  #       print msg.text
+  #     end
+  #   end
+  #   puts "\nDone! #{turn.tool_uses.size} tools used"
+  #
+  # @example Via one-shot query
+  #   turn = ClaudeAgent.query_turn(prompt: "What is 2+2?")
+  #   puts turn.text
+  #
+  class TurnResult
+    # All messages received during this turn
+    # @return [Array<Message>]
+    attr_reader :messages
+
+    def initialize
+      @messages = []
+      @result = nil
+    end
+
+    # Append a message to this turn
+    #
+    # @param message [Message] Any SDK message
+    # @return [self]
+    def <<(message)
+      @messages << message
+      @result = message if message.is_a?(ResultMessage)
+      self
+    end
+
+    # The final ResultMessage, or nil if the turn is still in progress
+    # @return [ResultMessage, nil]
+    def result
+      @result
+    end
+
+    # Whether a ResultMessage has been received
+    # @return [Boolean]
+    def complete?
+      !@result.nil?
+    end
+
+    # --- Text & Thinking ---
+
+    # All text content concatenated across assistant messages
+    # @return [String]
+    def text
+      assistant_messages.map(&:text).join
+    end
+
+    # All thinking content concatenated across assistant messages
+    # @return [String]
+    def thinking
+      assistant_messages.map(&:thinking).join
+    end
+
+    # --- Tool Use ---
+
+    # All tool use blocks across all assistant messages
+    # @return [Array<ToolUseBlock, ServerToolUseBlock>]
+    def tool_uses
+      assistant_messages.flat_map { |m| m.content.select { |b| b.is_a?(ToolUseBlock) || b.is_a?(ServerToolUseBlock) } }
+    end
+
+    # All tool result blocks from user messages (system-generated tool responses)
+    # @return [Array<ToolResultBlock, ServerToolResultBlock>]
+    def tool_results
+      user_messages
+        .select { |m| m.content.is_a?(Array) }
+        .flat_map { |m| m.content.select { |b| b.is_a?(ToolResultBlock) || b.is_a?(ServerToolResultBlock) } }
+    end
+
+    # Tool use/result pairs matched by ID
+    #
+    # Each entry is a Hash with:
+    # - `:tool_use` — the ToolUseBlock or ServerToolUseBlock
+    # - `:tool_result` — the matching ToolResultBlock/ServerToolResultBlock (nil if not yet received)
+    #
+    # @return [Array<Hash>]
+    def tool_executions
+      results_by_id = tool_results.each_with_object({}) { |r, h| h[r.tool_use_id] = r }
+      tool_uses.map do |tool_use|
+        { tool_use: tool_use, tool_result: results_by_id[tool_use.id] }
+      end
+    end
+
+    # --- Result Accessors ---
+
+    # Token usage from the ResultMessage
+    # @return [Hash, nil]
+    def usage
+      @result&.usage
+    end
+
+    # Total cost in USD
+    # @return [Float, nil]
+    def cost
+      @result&.total_cost_usd
+    end
+
+    # Wall-clock duration in milliseconds
+    # @return [Integer, nil]
+    def duration_ms
+      @result&.duration_ms
+    end
+
+    # API-only duration in milliseconds
+    # @return [Integer, nil]
+    def duration_api_ms
+      @result&.duration_api_ms
+    end
+
+    # Session ID for resumption
+    # @return [String, nil]
+    def session_id
+      @result&.session_id
+    end
+
+    # Number of turns in the session
+    # @return [Integer, nil]
+    def num_turns
+      @result&.num_turns
+    end
+
+    # Why the model stopped generating
+    # @return [String, nil]
+    def stop_reason
+      @result&.stop_reason
+    end
+
+    # Model used for this turn (from first assistant message)
+    # @return [String, nil]
+    def model
+      assistant_messages.first&.model
+    end
+
+    # Per-model usage breakdown
+    # @return [Hash, nil]
+    def model_usage
+      @result&.model_usage
+    end
+
+    # Structured output (if requested via options)
+    # @return [Object, nil]
+    def structured_output
+      @result&.structured_output
+    end
+
+    # Tools that were denied by permission callbacks
+    # @return [Array<SDKPermissionDenial>]
+    def permission_denials
+      @result&.permission_denials || []
+    end
+
+    # Errors from the result
+    # @return [Array<String>]
+    def errors
+      @result&.errors || []
+    end
+
+    # --- Status ---
+
+    # Whether the turn completed successfully
+    # @return [Boolean]
+    def success?
+      @result&.success? || false
+    end
+
+    # Whether the turn ended with an error
+    # @return [Boolean]
+    def error?
+      @result&.error? || false
+    end
+
+    # The result subtype (e.g. "success", "error_max_turns")
+    # @return [String, nil]
+    def subtype
+      @result&.subtype
+    end
+
+    # --- Filtered Message Access ---
+
+    # All AssistantMessages in this turn
+    # @return [Array<AssistantMessage>]
+    def assistant_messages
+      @messages.select { |m| m.is_a?(AssistantMessage) }
+    end
+
+    # All UserMessages in this turn (including system-generated tool result messages)
+    # @return [Array<UserMessage, UserMessageReplay>]
+    def user_messages
+      @messages.select { |m| m.is_a?(UserMessage) || m.is_a?(UserMessageReplay) }
+    end
+
+    # All StreamEvents in this turn
+    # @return [Array<StreamEvent>]
+    def stream_events
+      @messages.select { |m| m.is_a?(StreamEvent) }
+    end
+
+    # All content blocks across all assistant messages
+    # @return [Array<TextBlock, ThinkingBlock, ToolUseBlock, ...>]
+    def content_blocks
+      assistant_messages.flat_map(&:content)
+    end
+
+    # --- Inspection ---
+
+    def inspect
+      status = complete? ? (success? ? "success" : "error") : "in_progress"
+      parts = [ "#<#{self.class} status=#{status}" ]
+      parts << "messages=#{@messages.size}"
+      parts << "text=#{text.length}chars" unless text.empty?
+      parts << "tools=#{tool_uses.size}" unless tool_uses.empty?
+      parts << "cost=$#{cost}" if cost
+      parts << "duration=#{duration_ms}ms" if duration_ms
+      "#{parts.join(" ")}>"
+    end
+  end
+end

data/lib/claude_agent/types.rb

@@ -184,6 +184,51 @@ module ClaudeAgent
   #     max_turns: 10
   #   )
   #
+  # Session metadata returned by list_sessions (TypeScript SDK parity: SDKSessionInfo)
+  #
+  # @example
+  #   session = SessionInfo.new(
+  #     session_id: "abc-123",
+  #     summary: "Fix login bug",
+  #     last_modified: 1706000000000,
+  #     file_size: 4096,
+  #     custom_title: "Login fix",
+  #     first_prompt: "Help me fix the login page",
+  #     git_branch: "fix/login",
+  #     cwd: "/Users/dev/myapp"
+  #   )
+  #
+  SessionInfo = Data.define(
+    :session_id,
+    :summary,
+    :last_modified,
+    :file_size,
+    :custom_title,
+    :first_prompt,
+    :git_branch,
+    :cwd
+  ) do
+    def initialize(session_id:, summary:, last_modified:, file_size:, custom_title: nil, first_prompt: nil, git_branch: nil, cwd: nil)
+      super
+    end
+  end
+
+  # Message from a session transcript returned by get_session_messages (TypeScript SDK v0.2.59 parity)
+  #
+  # @example
+  #   msg = SessionMessage.new(
+  #     type: "user",
+  #     uuid: "abc-123",
+  #     session_id: "def-456",
+  #     message: { "role" => "user", "content" => [{ "type" => "text", "text" => "Hello" }] }
+  #   )
+  #
+  SessionMessage = Data.define(:type, :uuid, :session_id, :message, :parent_tool_use_id) do
+    def initialize(type:, uuid:, session_id:, message:, parent_tool_use_id: nil)
+      super
+    end
+  end
+
   AgentDefinition = Data.define(
     :description,
     :prompt,

data/lib/claude_agent/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeAgent
-  VERSION = "0.7.8"
+  VERSION = "0.7.10"
 end

data/lib/claude_agent.rb

@@ -16,15 +16,71 @@ require_relative "claude_agent/messages"
 require_relative "claude_agent/message_parser"
 require_relative "claude_agent/hooks"
 require_relative "claude_agent/permissions"
+require_relative "claude_agent/permission_request"
+require_relative "claude_agent/permission_queue"
 require_relative "claude_agent/control_protocol"
 require_relative "claude_agent/transport/base"
 require_relative "claude_agent/transport/subprocess"
 require_relative "claude_agent/mcp/tool"
 require_relative "claude_agent/mcp/server"
+require_relative "claude_agent/cumulative_usage"
+require_relative "claude_agent/event_handler"
+require_relative "claude_agent/turn_result"
+require_relative "claude_agent/tool_activity"
 require_relative "claude_agent/query"
 require_relative "claude_agent/client"
-require_relative "claude_agent/session"            # V2 Session API (unstable)
+require_relative "claude_agent/conversation"
+require_relative "claude_agent/session_paths"        # Shared session path infrastructure
+require_relative "claude_agent/list_sessions"       # Session discovery (TypeScript SDK v0.2.53 parity)
+require_relative "claude_agent/get_session_messages"    # Session transcript reading (TypeScript SDK v0.2.59 parity)
+require_relative "claude_agent/session_message_relation" # Chainable message query object
+require_relative "claude_agent/session"                  # Session finder + V2 Session API (unstable)
 
 module ClaudeAgent
-  # Re-export key classes at module level for convenience
+  class << self
+    # Create a new Conversation
+    #
+    # @see Conversation#initialize
+    # @return [Conversation]
+    def conversation(**kwargs)
+      Conversation.new(**kwargs)
+    end
+
+    # List past sessions with metadata
+    #
+    # Reads session metadata directly from disk without spawning a CLI subprocess.
+    # Returns SessionInfo objects sorted by last modified time (most recent first).
+    #
+    # @param dir [String, nil] Directory to scope sessions to (includes git worktrees).
+    #   When nil, returns sessions from all projects.
+    # @param limit [Integer, nil] Maximum number of sessions to return.
+    # @return [Array<SessionInfo>]
+    def list_sessions(dir: nil, limit: nil)
+      ListSessions.call(dir: dir, limit: limit)
+    end
+
+    # Read messages from a past session's transcript
+    #
+    # Reads the session JSONL file from disk, reconstructs the main conversation
+    # thread, and returns user/assistant messages with optional pagination.
+    #
+    # @param session_id [String] UUID of the session to read
+    # @param dir [String, nil] Project directory to find the session in.
+    #   When nil, searches all projects.
+    # @param limit [Integer, nil] Maximum number of messages to return.
+    # @param offset [Integer, nil] Number of messages to skip from the start.
+    # @return [Array<SessionMessage>]
+    def get_session_messages(session_id, dir: nil, limit: nil, offset: nil)
+      GetSessionMessages.call(session_id, dir: dir, limit: limit, offset: offset)
+    end
+
+    # Resume a previous Conversation by session ID
+    #
+    # @param session_id [String] Session ID to resume
+    # @see Conversation.resume
+    # @return [Conversation]
+    def resume_conversation(session_id, **kwargs)
+      Conversation.resume(session_id, **kwargs)
+    end
+  end
 end