claude_agent 0.1.0

data/lib/claude_agent/abort_controller.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Controller for aborting operations (TypeScript SDK parity)
+  #
+  # Provides a Ruby-idiomatic way to cancel ongoing SDK operations.
+  # Similar to JavaScript's AbortController pattern.
+  #
+  # @example Basic usage
+  #   controller = AbortController.new
+  #
+  #   Thread.new { sleep(5); controller.abort("Timeout") }
+  #
+  #   ClaudeAgent.query(
+  #     prompt: "Long running task",
+  #     options: Options.new(abort_controller: controller)
+  #   )
+  #
+  # @example With abort reason
+  #   controller.abort("User cancelled")
+  #   controller.signal.aborted?     # => true
+  #   controller.signal.reason       # => "User cancelled"
+  #
+  class AbortController
+    attr_reader :signal
+
+    def initialize
+      @signal = AbortSignal.new
+    end
+
+    # Abort the operation
+    # @param reason [String, nil] Reason for aborting
+    # @return [void]
+    def abort(reason = nil)
+      @signal.abort!(reason)
+    end
+  end
+
+  # Signal object that tracks abort state (TypeScript SDK parity)
+  #
+  # Thread-safe signal that can be checked by multiple consumers
+  # and triggers callbacks when aborted.
+  #
+  class AbortSignal
+    def initialize
+      @aborted = false
+      @reason = nil
+      @mutex = Mutex.new
+      @condition = ConditionVariable.new
+      @callbacks = []
+    end
+
+    # Check if signal has been aborted
+    # @return [Boolean]
+    def aborted?
+      @mutex.synchronize { @aborted }
+    end
+
+    # Get the abort reason
+    # @return [String, nil]
+    def reason
+      @mutex.synchronize { @reason }
+    end
+
+    # Register a callback for when abort is triggered
+    # @yield [reason] Called when abort occurs
+    # @return [void]
+    def on_abort(&block)
+      @mutex.synchronize do
+        if @aborted
+          block.call(@reason)
+        else
+          @callbacks << block
+        end
+      end
+    end
+
+    # Wait until aborted (with optional timeout)
+    # @param timeout [Numeric, nil] Timeout in seconds
+    # @return [Boolean] True if aborted, false if timed out
+    def wait(timeout: nil)
+      @mutex.synchronize do
+        return true if @aborted
+
+        @condition.wait(@mutex, timeout)
+        @aborted
+      end
+    end
+
+    # Raise AbortError if aborted (for checking in loops)
+    # @raise [AbortError] If signal has been aborted
+    def check!
+      raise AbortError, reason if aborted?
+    end
+
+    # @api private
+    # Trigger the abort
+    # @param reason [String, nil] Reason for aborting
+    def abort!(reason = nil)
+      callbacks_to_call = []
+      @mutex.synchronize do
+        return if @aborted
+
+        @aborted = true
+        @reason = reason || "Operation was aborted"
+        callbacks_to_call = @callbacks.dup
+        @callbacks.clear
+        @condition.broadcast
+      end
+      callbacks_to_call.each { |cb| cb.call(@reason) }
+    end
+  end
+end

data/lib/claude_agent/client.rb

@@ -0,0 +1,298 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Interactive, bidirectional client for Claude Code CLI
+  #
+  # Unlike {ClaudeAgent.query}, the Client provides:
+  # - Multiple conversation turns
+  # - Streaming responses
+  # - Ability to interrupt operations
+  # - Dynamic permission and model changes
+  # - File checkpointing and rewind
+  #
+  # @example Basic usage
+  #   client = ClaudeAgent::Client.new
+  #   client.connect
+  #   client.send_message("Hello!")
+  #   client.receive_response.each { |msg| puts msg }
+  #   client.disconnect
+  #
+  # @example With block (auto-disconnect)
+  #   ClaudeAgent::Client.open do |client|
+  #     client.send_message("Help me write a function")
+  #     client.receive_response.each { |msg| puts msg }
+  #
+  #     client.send_message("Now add tests")
+  #     client.receive_response.each { |msg| puts msg }
+  #   end
+  #
+  # @example With initial prompt
+  #   ClaudeAgent::Client.open(prompt: "You are a helpful coding assistant") do |client|
+  #     client.receive_response.each { |msg| puts msg }
+  #   end
+  #
+  class Client
+    attr_reader :options, :transport, :server_info
+
+    # Open a client with automatic cleanup
+    #
+    # @param options [Options, nil] Configuration options
+    # @param transport [Transport::Base, nil] Custom transport
+    # @param prompt [String, nil] Initial prompt
+    # @yield [Client] Connected client
+    # @return [Object] Result of block
+    def self.open(options: nil, transport: nil, prompt: nil)
+      client = new(options: options, transport: transport)
+      begin
+        client.connect(prompt: prompt)
+        yield client
+      ensure
+        client.disconnect
+      end
+    end
+
+    # Create a new client
+    #
+    # @param options [Options, nil] Configuration options
+    # @param transport [Transport::Base, nil] Custom transport (default: Subprocess)
+    def initialize(options: nil, transport: nil)
+      @options = options || Options.new
+      @transport = transport || Transport::Subprocess.new(options: @options)
+      @protocol = nil
+      @server_info = nil
+      @connected = false
+    end
+
+    # Connect to the CLI
+    #
+    # @param prompt [String, nil] Initial prompt to send
+    # @return [void]
+    def connect(prompt: nil)
+      raise CLIConnectionError, "Already connected" if @connected
+
+      ENV["CLAUDE_CODE_ENTRYPOINT"] = "sdk-rb-client"
+
+      @protocol = ControlProtocol.new(transport: @transport, options: @options)
+      @server_info = @protocol.start(streaming: true)
+      @connected = true
+
+      send_message(prompt) if prompt
+    end
+
+    # Disconnect from the CLI
+    #
+    # @return [void]
+    def disconnect
+      return unless @connected
+
+      @protocol&.stop
+      @protocol = nil
+      @connected = false
+    end
+
+    # Check if client is connected
+    #
+    # @return [Boolean]
+    def connected?
+      @connected
+    end
+
+    # Send a message to Claude
+    #
+    # @param content [String, Array] Message content
+    # @param session_id [String] Session ID (for multi-session support)
+    # @param uuid [String, nil] Message UUID for file checkpointing
+    # @return [void]
+    def send_message(content, session_id: "default", uuid: nil)
+      require_connection!
+      @protocol.send_user_message(content, session_id: session_id, uuid: uuid)
+    end
+
+    # Alias for send_message
+    alias_method :query, :send_message
+
+    # Receive all messages (blocks until connection closes)
+    #
+    # @yield [Message] Received messages
+    # @return [Enumerator<Message>] If no block given
+    def receive_messages(&block)
+      require_connection!
+
+      @protocol.each_message(&block)
+    end
+
+    # Receive messages until a ResultMessage is received
+    #
+    # @yield [Message] Received messages
+    # @return [Enumerator<Message>] If no block given
+    def receive_response(&block)
+      require_connection!
+
+      @protocol.receive_response(&block)
+    end
+
+    # Stream user input from an enumerable (TypeScript SDK parity)
+    #
+    # Sends each message from the input stream to Claude. When a block is given,
+    # messages are sent in a background thread while responses are yielded.
+    #
+    # @param stream [Enumerable] Input stream of messages (strings, hashes, or UserMessage)
+    # @param session_id [String] Default session ID for messages
+    # @yield [Message] Received messages (if block given)
+    # @return [void]
+    # @raise [CLIConnectionError] If not connected
+    # @raise [AbortError] If abort signal is triggered
+    #
+    # @example Without block (just send messages)
+    #   client.stream_input(["Hello", "How are you?"])
+    #   client.receive_response.each { |msg| puts msg }
+    #
+    # @example With block (concurrent send/receive)
+    #   client.stream_input(["Hello", "Follow up"]) do |msg|
+    #     case msg
+    #     when ClaudeAgent::AssistantMessage
+    #       puts msg.text
+    #     when ClaudeAgent::ResultMessage
+    #       puts "Done!"
+    #     end
+    #   end
+    #
+    def stream_input(stream, session_id: "default", &block)
+      require_connection!
+
+      if block_given?
+        @protocol.stream_conversation(stream, session_id: session_id, &block)
+      else
+        @protocol.stream_input(stream, session_id: session_id)
+      end
+    end
+
+    # Interrupt the current operation
+    #
+    # @return [void]
+    def interrupt
+      require_connection!
+
+      @protocol.interrupt
+    end
+
+    # Abort all pending operations (TypeScript SDK parity)
+    #
+    # This method:
+    # 1. Triggers the abort controller (if configured)
+    # 2. Aborts the protocol and terminates the transport
+    #
+    # @param reason [String, nil] Reason for aborting
+    # @return [void]
+    def abort!(reason = nil)
+      return unless @connected
+
+      @options.abort_controller&.abort(reason)
+      @protocol&.abort!
+    end
+
+    # Change the permission mode
+    #
+    # @param mode [String] New permission mode
+    # @return [Hash] Response
+    def set_permission_mode(mode)
+      require_connection!
+
+      @protocol.set_permission_mode(mode)
+    end
+
+    # Change the model
+    #
+    # @param model [String, nil] New model name (nil to use default)
+    # @return [Hash] Response
+    def set_model(model)
+      require_connection!
+
+      @protocol.set_model(model)
+    end
+
+    # Rewind files to the state at a specific user message
+    #
+    # @param user_message_id [String] UUID of the user message to rewind to
+    # @param dry_run [Boolean] If true, preview changes without modifying files
+    # @return [RewindFilesResult] Result with rewind information
+    def rewind_files(user_message_id, dry_run: false)
+      require_connection!
+
+      @protocol.rewind_files(user_message_id, dry_run: dry_run)
+    end
+
+    # Set maximum thinking tokens (TypeScript SDK parity)
+    #
+    # @param tokens [Integer, nil] Max thinking tokens (nil to reset)
+    # @return [Hash] Response
+    def set_max_thinking_tokens(tokens)
+      require_connection!
+
+      @protocol.set_max_thinking_tokens(tokens)
+    end
+
+    # Get available slash commands (TypeScript SDK parity)
+    #
+    # @return [Array<SlashCommand>]
+    def supported_commands
+      require_connection!
+
+      @protocol.supported_commands
+    end
+
+    # Get available models (TypeScript SDK parity)
+    #
+    # @return [Array<ModelInfo>]
+    def supported_models
+      require_connection!
+
+      @protocol.supported_models
+    end
+
+    # Get MCP server status (TypeScript SDK parity)
+    #
+    # @return [Array<McpServerStatus>]
+    def mcp_server_status
+      require_connection!
+
+      @protocol.mcp_server_status
+    end
+
+    # Get account information (TypeScript SDK parity)
+    #
+    # @return [AccountInfo]
+    def account_info
+      require_connection!
+
+      @protocol.account_info
+    end
+
+    # Dynamically set MCP servers for this session (TypeScript SDK parity)
+    #
+    # This replaces the current set of dynamically-added MCP servers.
+    # Servers that are removed will be disconnected, and new servers will be connected.
+    #
+    # @param servers [Hash] Map of server name to configuration
+    # @return [McpSetServersResult] Result with added, removed, and errors
+    #
+    # @example
+    #   result = client.set_mcp_servers({
+    #     "my-server" => { type: "stdio", command: "node", args: ["server.js"] }
+    #   })
+    #   puts "Added: #{result.added}"
+    #   puts "Removed: #{result.removed}"
+    #
+    def set_mcp_servers(servers)
+      require_connection!
+
+      @protocol.set_mcp_servers(servers)
+    end
+
+    private
+
+    def require_connection!
+      raise CLIConnectionError, "Not connected" unless @connected
+    end
+  end
+end

data/lib/claude_agent/content_blocks.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Text content block
+  #
+  # @example
+  #   block = TextBlock.new(text: "Hello, world!")
+  #   block.text # => "Hello, world!"
+  #
+  TextBlock = Data.define(:text) do
+    def type
+      :text
+    end
+
+    def to_h
+      { type: "text", text: text }
+    end
+  end
+
+  # Extended thinking content block
+  #
+  # @example
+  #   block = ThinkingBlock.new(thinking: "Let me consider...", signature: "abc123")
+  #   block.thinking # => "Let me consider..."
+  #
+  ThinkingBlock = Data.define(:thinking, :signature) do
+    def type
+      :thinking
+    end
+
+    def to_h
+      { type: "thinking", thinking: thinking, signature: signature }
+    end
+  end
+
+  # Tool use request block
+  #
+  # @example
+  #   block = ToolUseBlock.new(id: "tool_123", name: "Read", input: {file_path: "/tmp/file"})
+  #   block.name # => "Read"
+  #
+  ToolUseBlock = Data.define(:id, :name, :input) do
+    def type
+      :tool_use
+    end
+
+    def to_h
+      { type: "tool_use", id: id, name: name, input: input }
+    end
+  end
+
+  # Tool result block
+  #
+  # @example
+  #   block = ToolResultBlock.new(tool_use_id: "tool_123", content: "file contents", is_error: false)
+  #
+  ToolResultBlock = Data.define(:tool_use_id, :content, :is_error) do
+    def initialize(tool_use_id:, content: nil, is_error: nil)
+      super
+    end
+
+    def type
+      :tool_result
+    end
+
+    def to_h
+      h = { type: "tool_result", tool_use_id: tool_use_id }
+      h[:content] = content unless content.nil?
+      h[:is_error] = is_error unless is_error.nil?
+      h
+    end
+  end
+
+  # Server tool use block (for MCP servers)
+  #
+  ServerToolUseBlock = Data.define(:id, :name, :input, :server_name) do
+    def type
+      :server_tool_use
+    end
+
+    def to_h
+      { type: "server_tool_use", id: id, name: name, input: input, server_name: server_name }
+    end
+  end
+
+  # Server tool result block
+  #
+  ServerToolResultBlock = Data.define(:tool_use_id, :content, :is_error, :server_name) do
+    def initialize(tool_use_id:, server_name:, content: nil, is_error: nil)
+      super
+    end
+
+    def type
+      :server_tool_result
+    end
+
+    def to_h
+      h = { type: "server_tool_result", tool_use_id: tool_use_id, server_name: server_name }
+      h[:content] = content unless content.nil?
+      h[:is_error] = is_error unless is_error.nil?
+      h
+    end
+  end
+
+  # Image content block (TypeScript SDK parity)
+  #
+  # Supports both base64-encoded image data and URL sources.
+  #
+  # @example Base64 image
+  #   block = ImageContentBlock.new(
+  #     source: { type: "base64", media_type: "image/png", data: "..." }
+  #   )
+  #
+  # @example URL image
+  #   block = ImageContentBlock.new(
+  #     source: { type: "url", url: "https://example.com/image.png" }
+  #   )
+  #
+  ImageContentBlock = Data.define(:source) do
+    def type
+      :image
+    end
+
+    # Get the media type if available
+    # @return [String, nil]
+    def media_type
+      source.is_a?(Hash) ? (source[:media_type] || source["media_type"]) : nil
+    end
+
+    # Get the base64 data if available
+    # @return [String, nil]
+    def data
+      source.is_a?(Hash) ? (source[:data] || source["data"]) : nil
+    end
+
+    # Get the URL if this is a URL-sourced image
+    # @return [String, nil]
+    def url
+      source.is_a?(Hash) ? (source[:url] || source["url"]) : nil
+    end
+
+    # Get the source type (base64 or url)
+    # @return [String, nil]
+    def source_type
+      source.is_a?(Hash) ? (source[:type] || source["type"]) : nil
+    end
+
+    def to_h
+      { type: "image", source: source }
+    end
+  end
+
+  # All content block types
+  CONTENT_BLOCK_TYPES = [
+    TextBlock,
+    ThinkingBlock,
+    ToolUseBlock,
+    ToolResultBlock,
+    ServerToolUseBlock,
+    ServerToolResultBlock,
+    ImageContentBlock
+  ].freeze
+end