claude-agent-server 0.1.0

data/lib/claude_agent_server/services/message_serializer.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require 'claude_agent_sdk'
+
+module ClaudeAgentServer
+  module Services
+    module MessageSerializer
+      module_function
+
+      def serialize(message)
+        case message
+        when ClaudeAgentSDK::UserMessage
+          serialize_user_message(message)
+        when ClaudeAgentSDK::AssistantMessage
+          serialize_assistant_message(message)
+        when ClaudeAgentSDK::ResultMessage
+          serialize_result_message(message)
+        when ClaudeAgentSDK::TaskStartedMessage
+          serialize_task_started_message(message)
+        when ClaudeAgentSDK::TaskProgressMessage
+          serialize_task_progress_message(message)
+        when ClaudeAgentSDK::TaskNotificationMessage
+          serialize_task_notification_message(message)
+        when ClaudeAgentSDK::SystemMessage
+          serialize_system_message(message)
+        when ClaudeAgentSDK::StreamEvent
+          serialize_stream_event(message)
+        when ClaudeAgentSDK::RateLimitEvent
+          serialize_rate_limit_event(message)
+        else
+          { type: 'unknown', data: message.to_s }
+        end
+      end
+
+      def serialize_user_message(msg)
+        {
+          type: 'user',
+          content: serialize_content(msg.content),
+          uuid: msg.uuid,
+          parentToolUseId: msg.parent_tool_use_id
+        }.compact
+      end
+
+      def serialize_assistant_message(msg)
+        {
+          type: 'assistant',
+          content: serialize_content(msg.content),
+          model: msg.model,
+          parentToolUseId: msg.parent_tool_use_id,
+          error: msg.error
+        }.compact
+      end
+
+      def serialize_result_message(msg)
+        {
+          type: 'result',
+          subtype: msg.subtype,
+          durationMs: msg.duration_ms,
+          durationApiMs: msg.duration_api_ms,
+          isError: msg.is_error,
+          numTurns: msg.num_turns,
+          sessionId: msg.session_id,
+          stopReason: msg.stop_reason,
+          totalCostUsd: msg.total_cost_usd,
+          usage: msg.usage,
+          result: msg.result,
+          structuredOutput: msg.structured_output
+        }.compact
+      end
+
+      def serialize_task_started_message(msg)
+        {
+          type: 'system',
+          subtype: 'task_started',
+          taskId: msg.task_id,
+          description: msg.description,
+          uuid: msg.uuid,
+          sessionId: msg.session_id,
+          toolUseId: msg.tool_use_id,
+          taskType: msg.task_type
+        }.compact
+      end
+
+      def serialize_task_progress_message(msg)
+        {
+          type: 'system',
+          subtype: 'task_progress',
+          taskId: msg.task_id,
+          description: msg.description,
+          usage: msg.usage,
+          uuid: msg.uuid,
+          sessionId: msg.session_id,
+          toolUseId: msg.tool_use_id,
+          lastToolName: msg.last_tool_name
+        }.compact
+      end
+
+      def serialize_task_notification_message(msg)
+        {
+          type: 'system',
+          subtype: 'task_notification',
+          taskId: msg.task_id,
+          status: msg.status,
+          outputFile: msg.output_file,
+          summary: msg.summary,
+          uuid: msg.uuid,
+          sessionId: msg.session_id,
+          toolUseId: msg.tool_use_id,
+          usage: msg.usage
+        }.compact
+      end
+
+      def serialize_system_message(msg)
+        {
+          type: 'system',
+          subtype: msg.subtype,
+          data: msg.data
+        }.compact
+      end
+
+      def serialize_stream_event(msg)
+        {
+          type: 'stream_event',
+          uuid: msg.uuid,
+          sessionId: msg.session_id,
+          event: msg.event,
+          parentToolUseId: msg.parent_tool_use_id
+        }.compact
+      end
+
+      def serialize_rate_limit_event(msg)
+        {
+          type: 'rate_limit_event',
+          data: msg.data
+        }.compact
+      end
+
+      def serialize_content(content)
+        return content.map { |block| serialize_content_block(block) } if content.is_a?(Array)
+
+        content
+      end
+
+      def serialize_content_block(block)
+        case block
+        when ClaudeAgentSDK::TextBlock
+          { type: 'text', text: block.text }
+        when ClaudeAgentSDK::ThinkingBlock
+          { type: 'thinking', thinking: block.thinking, signature: block.signature }
+        when ClaudeAgentSDK::ToolUseBlock
+          { type: 'tool_use', id: block.id, name: block.name, input: block.input }
+        when ClaudeAgentSDK::ToolResultBlock
+          result = { type: 'tool_result', toolUseId: block.tool_use_id }
+          result[:content] = block.content if block.content
+          result[:isError] = block.is_error unless block.is_error.nil?
+          result
+        when ClaudeAgentSDK::UnknownBlock
+          block.data
+        else
+          block
+        end
+      end
+    end
+  end
+end

data/lib/claude_agent_server/services/options_builder.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'claude_agent_sdk'
+
+module ClaudeAgentServer
+  module Services
+    module OptionsBuilder
+      # Map of camelCase JSON keys to snake_case ClaudeAgentOptions kwargs
+      CAMEL_TO_SNAKE = {
+        'allowedTools' => :allowed_tools,
+        'disallowedTools' => :disallowed_tools,
+        'systemPrompt' => :system_prompt,
+        'mcpServers' => :mcp_servers,
+        'permissionMode' => :permission_mode,
+        'continueConversation' => :continue_conversation,
+        'resume' => :resume,
+        'maxTurns' => :max_turns,
+        'model' => :model,
+        'cwd' => :cwd,
+        'cliPath' => :cli_path,
+        'env' => :env,
+        'maxBudgetUsd' => :max_budget_usd,
+        'maxThinkingTokens' => :max_thinking_tokens,
+        'fallbackModel' => :fallback_model,
+        'outputFormat' => :output_format,
+        'includePartialMessages' => :include_partial_messages,
+        'forkSession' => :fork_session,
+        'enableFileCheckpointing' => :enable_file_checkpointing,
+        'effort' => :effort,
+        'appendAllowedTools' => :append_allowed_tools
+      }.freeze
+
+      module_function
+
+      def build(params)
+        kwargs = {}
+
+        params.each do |key, value|
+          snake_key = CAMEL_TO_SNAKE[key.to_s] || key.to_s.gsub(/([A-Z])/, '_\1').downcase.to_sym
+          kwargs[snake_key] = value
+        end
+
+        # Merge with server-level defaults
+        defaults = ClaudeAgentServer.config.default_sdk_options
+        merged = defaults.merge(kwargs)
+
+        # Force bypassPermissions for HTTP usage (no interactive terminal)
+        merged[:permission_mode] ||= 'bypassPermissions'
+
+        ClaudeAgentSDK::ClaudeAgentOptions.new(**merged)
+      end
+    end
+  end
+end

data/lib/claude_agent_server/services/query_executor.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'claude_agent_sdk'
+
+module ClaudeAgentServer
+  module Services
+    module QueryExecutor
+      module_function
+
+      def execute(prompt:, options:)
+        messages = []
+
+        ClaudeAgentSDK.query(prompt: prompt, options: options) do |message|
+          messages << MessageSerializer.serialize(message)
+        end
+
+        messages
+      end
+
+      def stream(prompt:, options:, &block)
+        ClaudeAgentSDK.query(prompt: prompt, options: options) do |message|
+          block.call(message)
+        end
+      end
+    end
+  end
+end

data/lib/claude_agent_server/services/session_manager.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'claude_agent_sdk'
+require 'async'
+require 'async/queue'
+
+module ClaudeAgentServer
+  module Services
+    # An indexed event wrapping an SDK message with a monotonic index
+    class SessionEvent
+      attr_reader :index, :message, :timestamp
+
+      def initialize(index:, message:)
+        @index = index
+        @message = message
+        @timestamp = Time.now
+      end
+    end
+
+    class SessionEntry
+      attr_reader :id, :client, :created_at, :status, :events
+      attr_accessor :last_activity
+
+      def initialize(id:, client:)
+        @id = id
+        @client = client
+        @created_at = Time.now
+        @last_activity = Time.now
+        @status = :connected
+        @events = []
+        @next_index = 0
+        @subscribers = []
+        @mutex = Mutex.new
+        @reader_task = nil
+      end
+
+      def message_count
+        @events.size
+      end
+
+      # Retrieve events by offset and limit (for polling)
+      def get_events(offset: 0, limit: nil)
+        @mutex.synchronize do
+          slice = @events[offset..] || []
+          limit ? slice.first(limit) : slice
+        end
+      end
+
+      def subscribe(offset: 0, &block)
+        queue = Async::Queue.new
+
+        # Replay missed events from offset
+        @mutex.synchronize do
+          @subscribers << queue
+          @events[offset..]&.each { |evt| queue.enqueue(evt) }
+        end
+
+        begin
+          loop do
+            event = queue.dequeue
+            break if event == :done
+
+            block.call(event)
+          end
+        ensure
+          @mutex.synchronize { @subscribers.delete(queue) }
+        end
+      end
+
+      def broadcast(message)
+        @mutex.synchronize do
+          event = SessionEvent.new(index: @next_index, message: message)
+          @next_index += 1
+          @events << event
+          @last_activity = Time.now
+          @subscribers.each { |q| q.enqueue(event) }
+        end
+      end
+
+      def finish
+        @mutex.synchronize do
+          @status = :finished
+          @subscribers.each { |q| q.enqueue(:done) }
+        end
+      end
+
+      def start_message_reader
+        @reader_task = Thread.new do
+          Async do
+            client.receive_messages do |message|
+              broadcast(message)
+              break if message.is_a?(ClaudeAgentSDK::ResultMessage)
+            end
+          rescue StandardError
+            # Reader ended (disconnect or error)
+          ensure
+            finish
+          end
+        end
+      end
+
+      def disconnect
+        @status = :disconnected
+        @reader_task&.kill
+        @client.disconnect
+        @mutex.synchronize do
+          @subscribers.each { |q| q.enqueue(:done) }
+          @subscribers.clear
+        end
+      end
+    end
+
+    class SessionManager
+      attr_reader :sessions
+
+      def initialize
+        @sessions = {}
+        @mutex = Mutex.new
+        @reaper_task = nil
+      end
+
+      def create_session(options:, prompt: nil, id: nil)
+        config = ClaudeAgentServer.config
+        id ||= SecureRandom.uuid
+
+        @mutex.synchronize do
+          raise SessionAlreadyExistsError, "Session '#{id}' already exists" if @sessions.key?(id)
+
+          if @sessions.size >= config.max_sessions
+            raise SessionLimitError, "Maximum session limit (#{config.max_sessions}) reached"
+          end
+        end
+
+        client = ClaudeAgentSDK::Client.new(options: options)
+        client.connect(prompt)
+
+        entry = SessionEntry.new(id: id, client: client)
+        @mutex.synchronize { @sessions[id] = entry }
+
+        entry.start_message_reader
+        entry
+      end
+
+      def get_session(id)
+        @mutex.synchronize { @sessions[id] } || raise(SessionNotFoundError, "Session '#{id}' not found")
+      end
+
+      def destroy_session(id)
+        entry = @mutex.synchronize { @sessions.delete(id) }
+        raise SessionNotFoundError, "Session '#{id}' not found" unless entry
+
+        entry.disconnect
+        entry
+      end
+
+      def list_sessions
+        @mutex.synchronize { @sessions.values.dup }
+      end
+
+      def start_reaper
+        @reaper_task = Async do |task|
+          loop do
+            task.sleep(60)
+            reap_expired_sessions
+          end
+        end
+      end
+
+      def stop_reaper
+        @reaper_task&.stop
+      end
+
+      def shutdown
+        stop_reaper
+        @mutex.synchronize do
+          @sessions.each_value(&:disconnect)
+          @sessions.clear
+        end
+      end
+
+      private
+
+      def reap_expired_sessions
+        ttl = ClaudeAgentServer.config.session_ttl
+        now = Time.now
+
+        expired_ids = @mutex.synchronize do
+          @sessions.select { |_, entry| now - entry.last_activity > ttl }.keys
+        end
+
+        expired_ids.each do |id|
+          entry = @mutex.synchronize { @sessions.delete(id) }
+          entry&.disconnect
+        end
+      end
+    end
+  end
+end

data/lib/claude_agent_server/services/sse_stream.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module ClaudeAgentServer
+  module Services
+    module SseStream
+      module_function
+
+      def stream_query(prompt:, options:)
+        index = 0
+        StreamBody.new do |stream|
+          QueryExecutor.stream(prompt: prompt, options: options) do |message|
+            serialized = MessageSerializer.serialize(message)
+            event_type = serialized[:type] || 'message'
+            stream.write(format_sse(event_type, serialized, id: index))
+            index += 1
+          end
+          stream.write(format_sse('done', { status: 'complete' }))
+        rescue IOError, Errno::EPIPE
+          # Client disconnected — exit cleanly
+        end
+      end
+
+      def stream_session(session_entry, last_event_id: nil)
+        offset = last_event_id ? last_event_id.to_i + 1 : 0
+
+        StreamBody.new do |stream|
+          session_entry.subscribe(offset: offset) do |event|
+            serialized = MessageSerializer.serialize(event.message)
+            event_type = serialized[:type] || 'message'
+            stream.write(format_sse(event_type, serialized, id: event.index))
+          end
+          stream.write(format_sse('done', { status: 'complete' }))
+        rescue IOError, Errno::EPIPE
+          # Client disconnected — session stays alive
+        end
+      end
+
+      def format_sse(event, data, id: nil)
+        parts = []
+        parts << "id: #{id}" unless id.nil?
+        parts << "event: #{event}"
+        parts << "data: #{JSON.generate(data)}"
+        "#{parts.join("\n")}\n\n"
+      end
+
+      # Rack 3 streaming body that yields chunks via a fiber
+      class StreamBody
+        def initialize(&block)
+          @block = block
+        end
+
+        def each(&chunk_block)
+          stream = StreamWriter.new(chunk_block)
+          @block.call(stream)
+        end
+      end
+
+      class StreamWriter
+        def initialize(chunk_block)
+          @chunk_block = chunk_block
+        end
+
+        def write(data)
+          @chunk_block.call(data)
+        end
+      end
+    end
+  end
+end

data/lib/claude_agent_server/version.rb

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

data/lib/claude_agent_server.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative 'claude_agent_server/version'
+require_relative 'claude_agent_server/errors'
+require_relative 'claude_agent_server/config'
+require_relative 'claude_agent_server/services/options_builder'
+require_relative 'claude_agent_server/services/message_serializer'
+require_relative 'claude_agent_server/services/query_executor'
+require_relative 'claude_agent_server/services/sse_stream'
+require_relative 'claude_agent_server/services/session_manager'
+require_relative 'claude_agent_server/middleware/request_id'
+require_relative 'claude_agent_server/middleware/error_handler'
+require_relative 'claude_agent_server/middleware/authentication'
+require_relative 'claude_agent_server/middleware/cors'
+require_relative 'claude_agent_server/app'
+
+module ClaudeAgentServer
+  @config = Config.new
+
+  class << self
+    attr_reader :config
+
+    def configure
+      yield @config if block_given?
+      @config
+    end
+
+    def reset_config!
+      @config = Config.new
+    end
+
+    def app
+      App.freeze.app
+    end
+  end
+end

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: claude-agent-server
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Community Contributors
+bindir: exe
+cert_chain: []
+date: 2026-03-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: claude-agent-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: falcon
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.48'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.48'
+- !ruby/object:Gem::Dependency
+  name: roda
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.85'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.85'
+description: REST + SSE HTTP wrapper for claude-agent-sdk. Exposes Claude Code as
+  a network service with session management, streaming, and authentication.
+email: []
+executables:
+- claude-agent-server
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- config.ru
+- docs/openapi.json
+- exe/claude-agent-server
+- lib/claude_agent_server.rb
+- lib/claude_agent_server/app.rb
+- lib/claude_agent_server/config.rb
+- lib/claude_agent_server/errors.rb
+- lib/claude_agent_server/middleware/authentication.rb
+- lib/claude_agent_server/middleware/cors.rb
+- lib/claude_agent_server/middleware/error_handler.rb
+- lib/claude_agent_server/middleware/request_id.rb
+- lib/claude_agent_server/services/message_serializer.rb
+- lib/claude_agent_server/services/options_builder.rb
+- lib/claude_agent_server/services/query_executor.rb
+- lib/claude_agent_server/services/session_manager.rb
+- lib/claude_agent_server/services/sse_stream.rb
+- lib/claude_agent_server/version.rb
+homepage: https://github.com/ya-luotao/claude-agent-server-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ya-luotao/claude-agent-server-ruby
+  source_code_uri: https://github.com/ya-luotao/claude-agent-server-ruby
+  changelog_uri: https://github.com/ya-luotao/claude-agent-server-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: HTTP server wrapping the Claude Agent Ruby SDK
+test_files: []