claude-agent-sdk 0.1.0

data/lib/claude_agent_sdk/types.rb

@@ -0,0 +1,358 @@
+# frozen_string_literal: true
+
+module ClaudeAgentSDK
+  # Content Blocks
+
+  # Text content block
+  class TextBlock
+    attr_accessor :text
+
+    def initialize(text:)
+      @text = text
+    end
+  end
+
+  # Thinking content block
+  class ThinkingBlock
+    attr_accessor :thinking, :signature
+
+    def initialize(thinking:, signature:)
+      @thinking = thinking
+      @signature = signature
+    end
+  end
+
+  # Tool use content block
+  class ToolUseBlock
+    attr_accessor :id, :name, :input
+
+    def initialize(id:, name:, input:)
+      @id = id
+      @name = name
+      @input = input
+    end
+  end
+
+  # Tool result content block
+  class ToolResultBlock
+    attr_accessor :tool_use_id, :content, :is_error
+
+    def initialize(tool_use_id:, content: nil, is_error: nil)
+      @tool_use_id = tool_use_id
+      @content = content
+      @is_error = is_error
+    end
+  end
+
+  # Message Types
+
+  # User message
+  class UserMessage
+    attr_accessor :content, :parent_tool_use_id
+
+    def initialize(content:, parent_tool_use_id: nil)
+      @content = content
+      @parent_tool_use_id = parent_tool_use_id
+    end
+  end
+
+  # Assistant message with content blocks
+  class AssistantMessage
+    attr_accessor :content, :model, :parent_tool_use_id
+
+    def initialize(content:, model:, parent_tool_use_id: nil)
+      @content = content
+      @model = model
+      @parent_tool_use_id = parent_tool_use_id
+    end
+  end
+
+  # System message with metadata
+  class SystemMessage
+    attr_accessor :subtype, :data
+
+    def initialize(subtype:, data:)
+      @subtype = subtype
+      @data = data
+    end
+  end
+
+  # Result message with cost and usage information
+  class ResultMessage
+    attr_accessor :subtype, :duration_ms, :duration_api_ms, :is_error,
+                  :num_turns, :session_id, :total_cost_usd, :usage, :result
+
+    def initialize(subtype:, duration_ms:, duration_api_ms:, is_error:,
+                   num_turns:, session_id:, total_cost_usd: nil, usage: nil, result: nil)
+      @subtype = subtype
+      @duration_ms = duration_ms
+      @duration_api_ms = duration_api_ms
+      @is_error = is_error
+      @num_turns = num_turns
+      @session_id = session_id
+      @total_cost_usd = total_cost_usd
+      @usage = usage
+      @result = result
+    end
+  end
+
+  # Stream event for partial message updates
+  class StreamEvent
+    attr_accessor :uuid, :session_id, :event, :parent_tool_use_id
+
+    def initialize(uuid:, session_id:, event:, parent_tool_use_id: nil)
+      @uuid = uuid
+      @session_id = session_id
+      @event = event
+      @parent_tool_use_id = parent_tool_use_id
+    end
+  end
+
+  # Agent definition configuration
+  class AgentDefinition
+    attr_accessor :description, :prompt, :tools, :model
+
+    def initialize(description:, prompt:, tools: nil, model: nil)
+      @description = description
+      @prompt = prompt
+      @tools = tools
+      @model = model
+    end
+  end
+
+  # Permission rule value
+  class PermissionRuleValue
+    attr_accessor :tool_name, :rule_content
+
+    def initialize(tool_name:, rule_content: nil)
+      @tool_name = tool_name
+      @rule_content = rule_content
+    end
+  end
+
+  # Permission update configuration
+  class PermissionUpdate
+    attr_accessor :type, :rules, :behavior, :mode, :directories, :destination
+
+    def initialize(type:, rules: nil, behavior: nil, mode: nil, directories: nil, destination: nil)
+      @type = type
+      @rules = rules
+      @behavior = behavior
+      @mode = mode
+      @directories = directories
+      @destination = destination
+    end
+
+    def to_h
+      result = { type: @type }
+      result[:destination] = @destination if @destination
+
+      case @type
+      when 'addRules', 'replaceRules', 'removeRules'
+        if @rules
+          result[:rules] = @rules.map do |rule|
+            {
+              toolName: rule.tool_name,
+              ruleContent: rule.rule_content
+            }
+          end
+        end
+        result[:behavior] = @behavior if @behavior
+      when 'setMode'
+        result[:mode] = @mode if @mode
+      when 'addDirectories', 'removeDirectories'
+        result[:directories] = @directories if @directories
+      end
+
+      result
+    end
+  end
+
+  # Tool permission context
+  class ToolPermissionContext
+    attr_accessor :signal, :suggestions
+
+    def initialize(signal: nil, suggestions: [])
+      @signal = signal
+      @suggestions = suggestions
+    end
+  end
+
+  # Permission results
+  class PermissionResultAllow
+    attr_accessor :behavior, :updated_input, :updated_permissions
+
+    def initialize(updated_input: nil, updated_permissions: nil)
+      @behavior = 'allow'
+      @updated_input = updated_input
+      @updated_permissions = updated_permissions
+    end
+  end
+
+  class PermissionResultDeny
+    attr_accessor :behavior, :message, :interrupt
+
+    def initialize(message: '', interrupt: false)
+      @behavior = 'deny'
+      @message = message
+      @interrupt = interrupt
+    end
+  end
+
+  # Hook matcher configuration
+  class HookMatcher
+    attr_accessor :matcher, :hooks
+
+    def initialize(matcher: nil, hooks: [])
+      @matcher = matcher
+      @hooks = hooks
+    end
+  end
+
+  # MCP Server configurations
+  class McpStdioServerConfig
+    attr_accessor :type, :command, :args, :env
+
+    def initialize(command:, args: nil, env: nil, type: 'stdio')
+      @type = type
+      @command = command
+      @args = args
+      @env = env
+    end
+
+    def to_h
+      result = { type: @type, command: @command }
+      result[:args] = @args if @args
+      result[:env] = @env if @env
+      result
+    end
+  end
+
+  class McpSSEServerConfig
+    attr_accessor :type, :url, :headers
+
+    def initialize(url:, headers: nil)
+      @type = 'sse'
+      @url = url
+      @headers = headers
+    end
+
+    def to_h
+      result = { type: @type, url: @url }
+      result[:headers] = @headers if @headers
+      result
+    end
+  end
+
+  class McpHttpServerConfig
+    attr_accessor :type, :url, :headers
+
+    def initialize(url:, headers: nil)
+      @type = 'http'
+      @url = url
+      @headers = headers
+    end
+
+    def to_h
+      result = { type: @type, url: @url }
+      result[:headers] = @headers if @headers
+      result
+    end
+  end
+
+  class McpSdkServerConfig
+    attr_accessor :type, :name, :instance
+
+    def initialize(name:, instance:)
+      @type = 'sdk'
+      @name = name
+      @instance = instance
+    end
+
+    def to_h
+      { type: @type, name: @name, instance: @instance }
+    end
+  end
+
+  # Claude Agent Options for configuring queries
+  class ClaudeAgentOptions
+    attr_accessor :allowed_tools, :system_prompt, :mcp_servers, :permission_mode,
+                  :continue_conversation, :resume, :max_turns, :disallowed_tools,
+                  :model, :permission_prompt_tool_name, :cwd, :cli_path, :settings,
+                  :add_dirs, :env, :extra_args, :max_buffer_size, :stderr,
+                  :can_use_tool, :hooks, :user, :include_partial_messages,
+                  :fork_session, :agents, :setting_sources
+
+    def initialize(
+      allowed_tools: [],
+      system_prompt: nil,
+      mcp_servers: {},
+      permission_mode: nil,
+      continue_conversation: false,
+      resume: nil,
+      max_turns: nil,
+      disallowed_tools: [],
+      model: nil,
+      permission_prompt_tool_name: nil,
+      cwd: nil,
+      cli_path: nil,
+      settings: nil,
+      add_dirs: [],
+      env: {},
+      extra_args: {},
+      max_buffer_size: nil,
+      stderr: nil,
+      can_use_tool: nil,
+      hooks: nil,
+      user: nil,
+      include_partial_messages: false,
+      fork_session: false,
+      agents: nil,
+      setting_sources: nil
+    )
+      @allowed_tools = allowed_tools
+      @system_prompt = system_prompt
+      @mcp_servers = mcp_servers
+      @permission_mode = permission_mode
+      @continue_conversation = continue_conversation
+      @resume = resume
+      @max_turns = max_turns
+      @disallowed_tools = disallowed_tools
+      @model = model
+      @permission_prompt_tool_name = permission_prompt_tool_name
+      @cwd = cwd
+      @cli_path = cli_path
+      @settings = settings
+      @add_dirs = add_dirs
+      @env = env
+      @extra_args = extra_args
+      @max_buffer_size = max_buffer_size
+      @stderr = stderr
+      @can_use_tool = can_use_tool
+      @hooks = hooks
+      @user = user
+      @include_partial_messages = include_partial_messages
+      @fork_session = fork_session
+      @agents = agents
+      @setting_sources = setting_sources
+    end
+
+    def dup_with(**changes)
+      new_options = self.dup
+      changes.each { |key, value| new_options.send("#{key}=", value) }
+      new_options
+    end
+  end
+
+  # SDK MCP Tool definition
+  class SdkMcpTool
+    attr_accessor :name, :description, :input_schema, :handler
+
+    def initialize(name:, description:, input_schema:, handler:)
+      @name = name
+      @description = description
+      @input_schema = input_schema
+      @handler = handler
+    end
+  end
+end

data/lib/claude_agent_sdk/version.rb

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

data/lib/claude_agent_sdk.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require_relative 'claude_agent_sdk/version'
+require_relative 'claude_agent_sdk/errors'
+require_relative 'claude_agent_sdk/types'
+require_relative 'claude_agent_sdk/transport'
+require_relative 'claude_agent_sdk/subprocess_cli_transport'
+require_relative 'claude_agent_sdk/message_parser'
+require_relative 'claude_agent_sdk/query'
+require_relative 'claude_agent_sdk/sdk_mcp_server'
+require 'async'
+require 'securerandom'
+
+# Claude Agent SDK for Ruby
+module ClaudeAgentSDK
+  # Query Claude Code for one-shot or unidirectional streaming interactions
+  #
+  # This function is ideal for simple, stateless queries where you don't need
+  # bidirectional communication or conversation management.
+  #
+  # @param prompt [String] The prompt to send to Claude
+  # @param options [ClaudeAgentOptions] Optional configuration
+  # @yield [Message] Each message from the conversation
+  # @return [Enumerator] if no block given
+  #
+  # @example Simple query
+  #   ClaudeAgentSDK.query(prompt: "What is 2 + 2?") do |message|
+  #     puts message
+  #   end
+  #
+  # @example With options
+  #   options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  #     allowed_tools: ['Read', 'Bash'],
+  #     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
+  #   end
+  def self.query(prompt:, options: nil, &block)
+    return enum_for(:query, prompt: prompt, options: options) unless block
+
+    options ||= ClaudeAgentOptions.new
+    ENV['CLAUDE_CODE_ENTRYPOINT'] = 'sdk-rb'
+
+    Async do
+      transport = SubprocessCLITransport.new(prompt, options)
+      begin
+        transport.connect
+        transport.read_messages do |data|
+          message = MessageParser.parse(data)
+          block.call(message)
+        end
+      ensure
+        transport.close
+      end
+    end.wait
+  end
+
+  # Client for bidirectional, interactive conversations with Claude Code
+  #
+  # This client provides full control over the conversation flow with support
+  # for streaming, hooks, permission callbacks, and dynamic message sending.
+  #
+  # @example Basic usage
+  #   Async do
+  #     client = ClaudeAgentSDK::Client.new
+  #     client.connect
+  #
+  #     client.query("What is the capital of France?")
+  #     client.receive_response do |msg|
+  #       puts msg if msg.is_a?(ClaudeAgentSDK::AssistantMessage)
+  #     end
+  #
+  #     client.disconnect
+  #   end
+  #
+  # @example With hooks
+  #   options = ClaudeAgentOptions.new(
+  #     hooks: {
+  #       'PreToolUse' => [
+  #         HookMatcher.new(
+  #           matcher: 'Bash',
+  #           hooks: [
+  #             ->(input, tool_use_id, context) {
+  #               # Return hook output
+  #               {}
+  #             }
+  #           ]
+  #         )
+  #       ]
+  #     }
+  #   )
+  #   client = ClaudeAgentSDK::Client.new(options: options)
+  class Client
+    attr_reader :query_handler
+
+    def initialize(options: nil)
+      @options = options || ClaudeAgentOptions.new
+      @transport = nil
+      @query_handler = nil
+      @connected = false
+      ENV['CLAUDE_CODE_ENTRYPOINT'] = 'sdk-rb-client'
+    end
+
+    # Connect to Claude with optional initial prompt
+    # @param prompt [String, Enumerator, nil] Initial prompt or message stream
+    def connect(prompt = nil)
+      return if @connected
+
+      # Validate and configure permission settings
+      configured_options = @options
+      if @options.can_use_tool
+        # can_use_tool requires streaming mode
+        if prompt.is_a?(String)
+          raise ArgumentError, 'can_use_tool callback requires streaming mode'
+        end
+
+        # can_use_tool and permission_prompt_tool_name are mutually exclusive
+        if @options.permission_prompt_tool_name
+          raise ArgumentError, 'can_use_tool callback cannot be used with permission_prompt_tool_name'
+        end
+
+        # Set permission_prompt_tool_name to stdio for control protocol
+        configured_options = @options.dup_with(permission_prompt_tool_name: 'stdio')
+      end
+
+      # Create transport
+      actual_prompt = prompt || ''
+      @transport = SubprocessCLITransport.new(actual_prompt, configured_options)
+      @transport.connect
+
+      # Extract SDK MCP servers
+      sdk_mcp_servers = {}
+      if configured_options.mcp_servers.is_a?(Hash)
+        configured_options.mcp_servers.each do |name, config|
+          sdk_mcp_servers[name] = config[:instance] if config.is_a?(Hash) && config[:type] == 'sdk'
+        end
+      end
+
+      # Convert hooks to internal format
+      hooks = convert_hooks_to_internal_format(configured_options.hooks) if configured_options.hooks
+
+      # Create Query handler
+      @query_handler = Query.new(
+        transport: @transport,
+        is_streaming_mode: true,
+        can_use_tool: configured_options.can_use_tool,
+        hooks: hooks,
+        sdk_mcp_servers: sdk_mcp_servers
+      )
+
+      # Start query handler and initialize
+      @query_handler.start
+      @query_handler.initialize_protocol
+
+      @connected = true
+    end
+
+    # Send a query to Claude
+    # @param prompt [String] The prompt to send
+    # @param session_id [String] Session identifier
+    def query(prompt, session_id: 'default')
+      raise CLIConnectionError, 'Not connected. Call connect() first' unless @connected
+
+      message = {
+        type: 'user',
+        message: { role: 'user', content: prompt },
+        parent_tool_use_id: nil,
+        session_id: session_id
+      }
+      @transport.write(JSON.generate(message) + "\n")
+    end
+
+    # Receive all messages from Claude
+    # @yield [Message] Each message received
+    def receive_messages(&block)
+      return enum_for(:receive_messages) unless block
+
+      raise CLIConnectionError, 'Not connected. Call connect() first' unless @connected
+
+      @query_handler.receive_messages do |data|
+        message = MessageParser.parse(data)
+        block.call(message)
+      end
+    end
+
+    # Receive messages until a ResultMessage is received
+    # @yield [Message] Each message received
+    def receive_response(&block)
+      return enum_for(:receive_response) unless block
+
+      receive_messages do |message|
+        block.call(message)
+        break if message.is_a?(ResultMessage)
+      end
+    end
+
+    # Send interrupt signal
+    def interrupt
+      raise CLIConnectionError, 'Not connected. Call connect() first' unless @connected
+      @query_handler.interrupt
+    end
+
+    # Change permission mode during conversation
+    # @param mode [String] Permission mode ('default', 'acceptEdits', 'bypassPermissions')
+    def set_permission_mode(mode)
+      raise CLIConnectionError, 'Not connected. Call connect() first' unless @connected
+      @query_handler.set_permission_mode(mode)
+    end
+
+    # Change the AI model during conversation
+    # @param model [String, nil] Model name or nil for default
+    def set_model(model)
+      raise CLIConnectionError, 'Not connected. Call connect() first' unless @connected
+      @query_handler.set_model(model)
+    end
+
+    # Get server initialization info
+    # @return [Hash, nil] Server info or nil
+    def server_info
+      @query_handler&.instance_variable_get(:@initialization_result)
+    end
+
+    # Disconnect from Claude
+    def disconnect
+      return unless @connected
+
+      @query_handler&.close
+      @query_handler = nil
+      @transport = nil
+      @connected = false
+    end
+
+    private
+
+    def convert_hooks_to_internal_format(hooks)
+      return nil unless hooks
+
+      internal_hooks = {}
+      hooks.each do |event, matchers|
+        internal_hooks[event.to_s] = []
+        matchers.each do |matcher|
+          internal_hooks[event.to_s] << {
+            matcher: matcher.matcher,
+            hooks: matcher.hooks
+          }
+        end
+      end
+      internal_hooks
+    end
+  end
+end