claude-agent-server 0.1.0

data/exe/claude-agent-server

@@ -0,0 +1,71 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'optparse'
+
+options = {}
+
+OptionParser.new do |opts|
+  opts.banner = 'Usage: claude-agent-server [options]'
+
+  opts.on('-p', '--port PORT', Integer, 'Port to listen on (default: 9292)') do |p|
+    options[:port] = p
+  end
+
+  opts.on('-b', '--bind HOST', 'Host to bind to (default: 0.0.0.0)') do |h|
+    options[:host] = h
+  end
+
+  opts.on('-t', '--token TOKEN', 'Authentication token') do |t|
+    options[:auth_token] = t
+  end
+
+  opts.on('--session-ttl SECONDS', Integer, 'Session TTL in seconds (default: 3600)') do |ttl|
+    options[:session_ttl] = ttl
+  end
+
+  opts.on('--max-sessions N', Integer, 'Maximum concurrent sessions (default: 100)') do |n|
+    options[:max_sessions] = n
+  end
+
+  opts.on('--cors-origins ORIGINS', 'Comma-separated CORS origins (default: *)') do |origins|
+    options[:cors_origins] = origins
+  end
+
+  opts.on('-v', '--version', 'Show version') do
+    require_relative '../lib/claude_agent_server/version'
+    puts "claude-agent-server #{ClaudeAgentServer::VERSION}"
+    exit
+  end
+
+  opts.on('-h', '--help', 'Show help') do
+    puts opts
+    exit
+  end
+end.parse!
+
+require_relative '../lib/claude_agent_server'
+
+ClaudeAgentServer.configure do |config|
+  config.port = options[:port] if options[:port]
+  config.host = options[:host] if options[:host]
+  config.auth_token = options[:auth_token] if options[:auth_token]
+  config.session_ttl = options[:session_ttl] if options[:session_ttl]
+  config.max_sessions = options[:max_sessions] if options[:max_sessions]
+  config.cors_origins = options[:cors_origins] if options[:cors_origins]
+end
+
+config = ClaudeAgentServer.config
+
+puts "Starting claude-agent-server v#{ClaudeAgentServer::VERSION}"
+puts "Listening on http://#{config.host}:#{config.port}"
+puts "Auth: #{config.auth_enabled? ? 'enabled' : 'disabled'}"
+puts "Max sessions: #{config.max_sessions}, TTL: #{config.session_ttl}s"
+
+# Use array form to avoid shell injection
+Kernel.exec(
+  'falcon', 'serve',
+  '--bind', "http://#{config.host}:#{config.port}",
+  '--count', '1',
+  '--config', File.expand_path('../../config.ru', __dir__)
+)

data/lib/claude_agent_server/app.rb

@@ -0,0 +1,337 @@
+# frozen_string_literal: true
+
+require 'roda'
+require 'json'
+require 'claude_agent_sdk'
+
+module ClaudeAgentServer
+  class App < Roda
+    plugin :request_headers
+    plugin :all_verbs
+
+    @session_manager = Services::SessionManager.new
+
+    class << self
+      attr_reader :session_manager
+    end
+
+    use Middleware::RequestId
+    use Middleware::Cors
+    use Middleware::Authentication
+    use Middleware::ErrorHandler
+
+    route do |r| # rubocop:disable Metrics/BlockLength
+      # GET /health (outside /v1 — always accessible)
+      r.on 'health' do
+        r.get do
+          json_response({ status: 'ok' })
+        end
+      end
+
+      # All API routes under /v1
+      r.on 'v1' do # rubocop:disable Metrics/BlockLength
+        # GET /v1/health
+        r.on 'health' do
+          r.get do
+            json_response({ status: 'ok' })
+          end
+        end
+
+        # GET /v1/openapi.json
+        r.on 'openapi.json' do
+          r.get do
+            spec_path = File.expand_path('../../docs/openapi.json', __dir__)
+            response['content-type'] = 'application/json'
+            File.read(spec_path)
+          end
+        end
+
+        # GET /v1/info
+        r.on 'info' do
+          r.get do
+            manager = self.class.session_manager
+            json_response({
+                            version: ClaudeAgentServer::VERSION,
+                            sdkVersion: ClaudeAgentSDK::VERSION,
+                            activeSessions: manager.sessions.size
+                          })
+          end
+        end
+
+        # /v1/query routes
+        r.on 'query' do
+          # POST /v1/query/stream
+          r.on 'stream' do
+            r.post do
+              params = parse_json_body(request)
+              prompt = params['prompt'] || params[:prompt]
+              raise ArgumentError, 'Missing required field: prompt' unless prompt
+
+              sdk_options = params['options'] || params[:options] || {}
+              options = Services::OptionsBuilder.build(sdk_options)
+
+              response['content-type'] = 'text/event-stream'
+              response['cache-control'] = 'no-cache'
+              response['x-accel-buffering'] = 'no'
+
+              body = Services::SseStream.stream_query(prompt: prompt, options: options)
+              r.halt [200, response.headers, body]
+            end
+          end
+
+          # POST /v1/query
+          r.is do
+            r.post do
+              params = parse_json_body(request)
+              prompt = params['prompt'] || params[:prompt]
+              raise ArgumentError, 'Missing required field: prompt' unless prompt
+
+              sdk_options = params['options'] || params[:options] || {}
+              options = Services::OptionsBuilder.build(sdk_options)
+
+              messages = Services::QueryExecutor.execute(prompt: prompt, options: options)
+              json_response({ messages: messages })
+            end
+          end
+        end
+
+        # /v1/cli-sessions routes (read-only CLI session browsing)
+        r.on 'cli-sessions' do # rubocop:disable Metrics/BlockLength
+          r.is do
+            r.get do
+              params = r.params
+              directory = params['directory']
+              limit = params['limit']&.to_i
+              include_worktrees = params['includeWorktrees'] != 'false'
+
+              sessions = ClaudeAgentSDK.list_sessions(
+                directory: directory, limit: limit, include_worktrees: include_worktrees
+              )
+              json_response({ sessions: sessions.map { |s| serialize_sdk_session(s) } })
+            end
+          end
+
+          r.on String do |session_id|
+            r.on 'messages' do
+              r.get do
+                params = r.params
+                messages = ClaudeAgentSDK.get_session_messages(
+                  session_id: session_id,
+                  directory: params['directory'],
+                  limit: params['limit']&.to_i,
+                  offset: (params['offset'] || '0').to_i
+                )
+                json_response({
+                                sessionId: session_id,
+                                messages: messages.map { |m| serialize_session_message(m) }
+                              })
+              end
+            end
+          end
+        end
+
+        # /v1/sessions routes
+        r.on 'sessions' do # rubocop:disable Metrics/BlockLength
+          manager = self.class.session_manager
+
+          r.is do
+            r.get do
+              entries = manager.list_sessions
+              json_response({ sessions: entries.map { |e| serialize_session_info(e) } })
+            end
+
+            r.post do
+              params = parse_json_body(request)
+              prompt = params['prompt'] || params[:prompt]
+              session_id = params['id'] || params[:id]
+              sdk_options = params['options'] || params[:options] || {}
+              options = Services::OptionsBuilder.build(sdk_options)
+
+              entry = manager.create_session(options: options, prompt: prompt, id: session_id)
+              response.status = 201
+              json_response(serialize_session_info(entry))
+            end
+          end
+
+          r.on String do |session_id| # rubocop:disable Metrics/BlockLength
+            r.is do
+              r.get do
+                entry = manager.get_session(session_id)
+                json_response(serialize_session_info(entry))
+              end
+
+              r.delete do
+                manager.destroy_session(session_id)
+                json_response({ status: 'disconnected', id: session_id })
+              end
+            end
+
+            # /v1/sessions/:id/events — offset-based polling
+            r.on 'events' do
+              # GET /v1/sessions/:id/events/sse — SSE stream with resume
+              r.on 'sse' do
+                r.get do
+                  entry = manager.get_session(session_id)
+                  last_event_id = env['HTTP_LAST_EVENT_ID']
+
+                  response['content-type'] = 'text/event-stream'
+                  response['cache-control'] = 'no-cache'
+                  response['x-accel-buffering'] = 'no'
+
+                  body = Services::SseStream.stream_session(entry, last_event_id: last_event_id)
+                  r.halt [200, response.headers, body]
+                end
+              end
+
+              # GET /v1/sessions/:id/events?offset=N&limit=M
+              r.is do
+                r.get do
+                  entry = manager.get_session(session_id)
+                  params = r.params
+                  offset = (params['offset'] || '0').to_i
+                  limit = params['limit']&.to_i
+
+                  events = entry.get_events(offset: offset, limit: limit)
+                  json_response({
+                                  sessionId: session_id,
+                                  events: events.map { |e| serialize_event(e) },
+                                  nextOffset: events.empty? ? offset : events.last.index + 1
+                                })
+                end
+              end
+            end
+
+            # POST /v1/sessions/:id/messages
+            r.on 'messages' do
+              # GET /v1/sessions/:id/messages/stream (legacy SSE)
+              r.on 'stream' do
+                r.get do
+                  entry = manager.get_session(session_id)
+                  last_event_id = env['HTTP_LAST_EVENT_ID']
+
+                  response['content-type'] = 'text/event-stream'
+                  response['cache-control'] = 'no-cache'
+                  response['x-accel-buffering'] = 'no'
+
+                  body = Services::SseStream.stream_session(entry, last_event_id: last_event_id)
+                  r.halt [200, response.headers, body]
+                end
+              end
+
+              r.is do
+                r.post do
+                  entry = manager.get_session(session_id)
+                  params = parse_json_body(request)
+                  prompt = params['prompt'] || params[:prompt]
+                  raise ArgumentError, 'Missing required field: prompt' unless prompt
+
+                  entry.last_activity = Time.now
+                  entry.client.query(prompt)
+                  json_response({ status: 'sent', sessionId: session_id })
+                end
+              end
+            end
+
+            r.on 'interrupt' do
+              r.post do
+                entry = manager.get_session(session_id)
+                entry.client.interrupt
+                entry.last_activity = Time.now
+                json_response({ status: 'interrupted', sessionId: session_id })
+              end
+            end
+
+            r.on 'model' do
+              r.post do
+                entry = manager.get_session(session_id)
+                params = parse_json_body(request)
+                model = params['model'] || params[:model]
+                raise ArgumentError, 'Missing required field: model' unless model
+
+                entry.client.set_model(model)
+                entry.last_activity = Time.now
+                json_response({ status: 'model_changed', model: model, sessionId: session_id })
+              end
+            end
+
+            r.on 'mcp-status' do
+              r.get do
+                entry = manager.get_session(session_id)
+                mcp_status = entry.client.get_mcp_status
+                json_response({ sessionId: session_id, mcpStatus: mcp_status })
+              end
+            end
+
+            r.on 'history' do
+              r.get do
+                entry = manager.get_session(session_id)
+                events = entry.events
+                json_response({
+                                sessionId: session_id,
+                                messages: events.map { |e| serialize_event(e) }
+                              })
+              end
+            end
+          end
+        end
+      end
+    end
+
+    private
+
+    def json_response(data)
+      response['content-type'] = 'application/json'
+      JSON.generate(data)
+    end
+
+    def parse_json_body(request)
+      body = request.body.read
+      return {} if body.nil? || body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError => e
+      raise ArgumentError, "Invalid JSON body: #{e.message}"
+    end
+
+    def serialize_session_info(entry)
+      {
+        id: entry.id,
+        status: entry.status.to_s,
+        createdAt: entry.created_at.iso8601,
+        lastActivity: entry.last_activity.iso8601,
+        messageCount: entry.message_count
+      }
+    end
+
+    def serialize_event(event)
+      {
+        index: event.index,
+        timestamp: event.timestamp.iso8601,
+        message: Services::MessageSerializer.serialize(event.message)
+      }
+    end
+
+    def serialize_sdk_session(session)
+      {
+        sessionId: session.session_id,
+        summary: session.summary,
+        lastModified: session.last_modified,
+        fileSize: session.file_size,
+        customTitle: session.custom_title,
+        firstPrompt: session.first_prompt,
+        gitBranch: session.git_branch,
+        cwd: session.cwd
+      }.compact
+    end
+
+    def serialize_session_message(msg)
+      {
+        type: msg.type,
+        uuid: msg.uuid,
+        sessionId: msg.session_id,
+        message: msg.message,
+        parentToolUseId: msg.parent_tool_use_id
+      }.compact
+    end
+  end
+end

data/lib/claude_agent_server/config.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module ClaudeAgentServer
+  class Config
+    attr_accessor :host, :port, :auth_token, :cors_origins, :session_ttl,
+                  :max_sessions, :default_sdk_options, :log_level
+
+    def initialize
+      @host = ENV.fetch('CLAUDE_SERVER_HOST', '0.0.0.0')
+      @port = ENV.fetch('CLAUDE_SERVER_PORT', '9292').to_i
+      @auth_token = ENV.fetch('CLAUDE_SERVER_AUTH_TOKEN', nil)
+      @cors_origins = ENV.fetch('CLAUDE_SERVER_CORS_ORIGINS', '*')
+      @session_ttl = ENV.fetch('CLAUDE_SERVER_SESSION_TTL', '3600').to_i
+      @max_sessions = ENV.fetch('CLAUDE_SERVER_MAX_SESSIONS', '100').to_i
+      @default_sdk_options = {}
+      @log_level = ENV.fetch('CLAUDE_SERVER_LOG_LEVEL', 'info')
+    end
+
+    def auth_enabled?
+      !@auth_token.nil? && !@auth_token.empty?
+    end
+
+    def allowed_origins
+      return ['*'] if @cors_origins == '*'
+
+      @cors_origins.split(',').map(&:strip)
+    end
+  end
+end

data/lib/claude_agent_server/errors.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module ClaudeAgentServer
+  URN_PREFIX = 'urn:claude-agent-server:error'
+
+  class ServerError < StandardError
+    def error_type = 'server_error'
+    def status_code = 500
+    def title = 'Server Error'
+    def urn = "#{URN_PREFIX}:#{error_type}"
+
+    def to_problem_details
+      {
+        type: urn,
+        title: title,
+        status: status_code,
+        detail: message
+      }
+    end
+  end
+
+  class ConfigError < ServerError
+    def error_type = 'config_error'
+    def status_code = 400
+    def title = 'Configuration Error'
+  end
+
+  class SessionNotFoundError < ServerError
+    def error_type = 'session_not_found'
+    def status_code = 404
+    def title = 'Session Not Found'
+  end
+
+  class SessionAlreadyExistsError < ServerError
+    def error_type = 'session_already_exists'
+    def status_code = 409
+    def title = 'Session Already Exists'
+  end
+
+  class SessionLimitError < ServerError
+    def error_type = 'session_limit_reached'
+    def status_code = 429
+    def title = 'Session Limit Reached'
+  end
+
+  class AuthenticationError < ServerError
+    def error_type = 'unauthorized'
+    def status_code = 401
+    def title = 'Unauthorized'
+  end
+end

data/lib/claude_agent_server/middleware/authentication.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'openssl'
+
+module ClaudeAgentServer
+  module Middleware
+    class Authentication
+      SKIP_PATHS = %w[/health /v1/health].freeze
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        return @app.call(env) unless ClaudeAgentServer.config.auth_enabled?
+        return @app.call(env) if skip_auth?(env)
+
+        token = extract_token(env)
+        return unauthorized_response unless token && timing_safe_compare(token, ClaudeAgentServer.config.auth_token)
+
+        @app.call(env)
+      end
+
+      private
+
+      def skip_auth?(env)
+        SKIP_PATHS.include?(env['PATH_INFO'])
+      end
+
+      def extract_token(env)
+        auth_header = env['HTTP_AUTHORIZATION']
+        return nil unless auth_header
+
+        match = auth_header.match(/\ABearer\s+(.+)\z/i)
+        match&.captures&.first
+      end
+
+      def timing_safe_compare(provided, expected)
+        OpenSSL.fixed_length_secure_compare(
+          OpenSSL::Digest::SHA256.digest(provided),
+          OpenSSL::Digest::SHA256.digest(expected)
+        )
+      end
+
+      def unauthorized_response
+        body = JSON.generate({
+                               type: "#{URN_PREFIX}:unauthorized",
+                               title: 'Unauthorized',
+                               status: 401,
+                               detail: 'Invalid or missing authentication token'
+                             })
+        [401, { 'content-type' => 'application/problem+json' }, [body]]
+      end
+    end
+  end
+end

data/lib/claude_agent_server/middleware/cors.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module ClaudeAgentServer
+  module Middleware
+    class Cors
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        origin = env['HTTP_ORIGIN']
+
+        return preflight_response(origin) if env['REQUEST_METHOD'] == 'OPTIONS'
+
+        status, headers, body = @app.call(env)
+        add_cors_headers(headers, origin)
+        [status, headers, body]
+      end
+
+      private
+
+      def preflight_response(origin)
+        headers = {
+          'content-type' => 'text/plain',
+          'access-control-max-age' => '86400'
+        }
+        add_cors_headers(headers, origin)
+        headers['access-control-allow-methods'] = 'GET, POST, DELETE, OPTIONS'
+        headers['access-control-allow-headers'] = 'Content-Type, Authorization, X-Request-Id'
+        [204, headers, []]
+      end
+
+      def add_cors_headers(headers, origin)
+        allowed = ClaudeAgentServer.config.allowed_origins
+
+        if allowed.include?('*')
+          headers['access-control-allow-origin'] = '*'
+        elsif origin && allowed.include?(origin)
+          headers['access-control-allow-origin'] = origin
+          headers['vary'] = 'Origin'
+        end
+
+        headers['access-control-expose-headers'] = 'X-Request-Id'
+      end
+    end
+  end
+end

data/lib/claude_agent_server/middleware/error_handler.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module ClaudeAgentServer
+  module Middleware
+    class ErrorHandler
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        @app.call(env)
+      rescue ServerError => e
+        problem_response(e.status_code, e.to_problem_details)
+      rescue ClaudeAgentSDK::CLINotFoundError => e
+        problem_response(503, problem(503, 'cli_not_found', 'CLI Not Found', e.message))
+      rescue ClaudeAgentSDK::CLIConnectionError => e
+        problem_response(502, problem(502, 'cli_connection_error', 'CLI Connection Error', e.message))
+      rescue ClaudeAgentSDK::ProcessError => e
+        problem_response(502, problem(502, 'cli_process_error', 'CLI Process Error', e.message))
+      rescue ClaudeAgentSDK::ClaudeSDKError => e
+        problem_response(502, problem(502, 'sdk_error', 'SDK Error', e.message))
+      rescue ArgumentError => e
+        problem_response(400, problem(400, 'invalid_request', 'Invalid Request', e.message))
+      rescue StandardError => e
+        problem_response(500, problem(500, 'internal_error', 'Internal Error', e.message))
+      end
+
+      private
+
+      def problem(status, error_type, title, detail)
+        {
+          type: "#{URN_PREFIX}:#{error_type}",
+          title: title,
+          status: status,
+          detail: detail
+        }
+      end
+
+      def problem_response(status, body)
+        [status, { 'content-type' => 'application/problem+json' }, [JSON.generate(body)]]
+      end
+    end
+  end
+end

data/lib/claude_agent_server/middleware/request_id.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module ClaudeAgentServer
+  module Middleware
+    class RequestId
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        request_id = env['HTTP_X_REQUEST_ID'] || SecureRandom.uuid
+        env['claude_agent_server.request_id'] = request_id
+
+        status, headers, body = @app.call(env)
+        headers['x-request-id'] = request_id
+        [status, headers, body]
+      end
+    end
+  end
+end