claude_agent 0.7.12 → 0.7.14

data/lib/claude_agent/control_protocol/commands.rb

@@ -0,0 +1,304 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  class ControlProtocol
+    # Public control commands: interrupt, model/permission changes,
+    # MCP management, task control, and query methods.
+    module Commands
+      # Send an interrupt request
+      # @return [void]
+      def interrupt
+        send_control_request(subtype: "interrupt")
+      end
+
+      # Change the permission mode
+      # @param mode [String] New permission mode
+      # @return [Hash] Response
+      def set_permission_mode(mode)
+        send_control_request(subtype: "set_permission_mode", mode: mode)
+      end
+
+      # Change the model
+      # @param model [String, nil] New model name
+      # @return [Hash] Response
+      def set_model(model)
+        send_control_request(subtype: "set_model", model: model)
+      end
+
+      # Rewind files to a previous state
+      # @param user_message_id [String] UUID of 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)
+        request = { user_message_id: user_message_id }
+        request[:dry_run] = dry_run if dry_run
+
+        response = send_control_request(subtype: "rewind_files", **request)
+
+        RewindFilesResult.new(
+          can_rewind: response["canRewind"] || response["can_rewind"] || false,
+          error: response["error"],
+          files_changed: response["filesChanged"] || response["files_changed"],
+          insertions: response["insertions"],
+          deletions: response["deletions"]
+        )
+      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)
+        send_control_request(subtype: "set_max_thinking_tokens", max_thinking_tokens: tokens)
+      end
+
+      # Get available slash commands (TypeScript SDK parity)
+      # @return [Array<SlashCommand>]
+      def supported_commands
+        response = send_control_request(subtype: "supported_commands")
+        (response["commands"] || []).map do |cmd|
+          SlashCommand.new(
+            name: cmd["name"],
+            description: cmd["description"],
+            argument_hint: cmd["argumentHint"]
+          )
+        end
+      end
+
+      # Get full initialization result (TypeScript SDK parity)
+      #
+      # Sends the supported_commands request and maps the full response including
+      # commands, output style, available output styles, models, and account info.
+      #
+      # @return [InitializationResult]
+      def initialization_result
+        response = send_control_request(subtype: "supported_commands")
+
+        commands = (response["commands"] || []).map do |cmd|
+          SlashCommand.new(
+            name: cmd["name"],
+            description: cmd["description"],
+            argument_hint: cmd["argumentHint"]
+          )
+        end
+
+        models = (response["models"] || []).map do |model|
+          ModelInfo.new(
+            value: model["value"],
+            display_name: model["displayName"],
+            description: model["description"],
+            supports_effort: model["supportsEffort"],
+            supported_effort_levels: model["supportedEffortLevels"],
+            supports_adaptive_thinking: model["supportsAdaptiveThinking"],
+            supports_fast_mode: model["supportsFastMode"],
+            supports_auto_mode: model["supportsAutoMode"]
+          )
+        end
+
+        account_data = response["account"]
+        account = if account_data
+          AccountInfo.new(
+            email: account_data["email"],
+            organization: account_data["organization"],
+            subscription_type: account_data["subscriptionType"],
+            token_source: account_data["tokenSource"],
+            api_key_source: account_data["apiKeySource"]
+          )
+        end
+
+        agents = (response["agents"] || []).map do |agent|
+          AgentInfo.new(
+            name: agent["name"],
+            description: agent["description"],
+            model: agent["model"]
+          )
+        end
+
+        InitializationResult.new(
+          commands: commands,
+          output_style: response["output_style"],
+          available_output_styles: response["available_output_styles"] || [],
+          models: models,
+          account: account,
+          agents: agents,
+          fast_mode_state: response["fast_mode_state"]
+        )
+      end
+
+      # Get available models (TypeScript SDK parity)
+      # @return [Array<ModelInfo>]
+      def supported_models
+        response = send_control_request(subtype: "supported_models")
+        (response["models"] || []).map do |model|
+          ModelInfo.new(
+            value: model["value"],
+            display_name: model["displayName"],
+            description: model["description"],
+            supports_effort: model["supportsEffort"],
+            supported_effort_levels: model["supportedEffortLevels"],
+            supports_adaptive_thinking: model["supportsAdaptiveThinking"],
+            supports_fast_mode: model["supportsFastMode"],
+            supports_auto_mode: model["supportsAutoMode"]
+          )
+        end
+      end
+
+      # Get available agents (TypeScript SDK v0.2.63 parity)
+      # @return [Array<AgentInfo>]
+      def supported_agents
+        response = send_control_request(subtype: "supported_agents")
+        (response["agents"] || []).map do |agent|
+          AgentInfo.new(
+            name: agent["name"],
+            description: agent["description"],
+            model: agent["model"]
+          )
+        end
+      end
+
+      # Get MCP server status (TypeScript SDK parity)
+      # @return [Array<McpServerStatus>]
+      def mcp_server_status
+        response = send_control_request(subtype: "mcp_server_status")
+        (response["servers"] || []).map do |server|
+          McpServerStatus.new(
+            name: server["name"],
+            status: server["status"],
+            server_info: server["serverInfo"],
+            error: server["error"],
+            config: server["config"],
+            scope: server["scope"],
+            tools: server["tools"]
+          )
+        end
+      end
+
+      # Get account information (TypeScript SDK parity)
+      # @return [AccountInfo]
+      def account_info
+        response = send_control_request(subtype: "account_info")
+        AccountInfo.new(
+          email: response["email"],
+          organization: response["organization"],
+          subscription_type: response["subscriptionType"],
+          token_source: response["tokenSource"],
+          api_key_source: response["apiKeySource"]
+        )
+      end
+
+      # Reconnect to an MCP server (TypeScript SDK parity)
+      #
+      # Attempts to reconnect to a disconnected or errored MCP server.
+      #
+      # @param server_name [String] Name of the MCP server to reconnect
+      # @return [Hash] Response from the CLI
+      #
+      # @example
+      #   protocol.mcp_reconnect("my-server")
+      #
+      def mcp_reconnect(server_name)
+        send_control_request(subtype: "mcp_reconnect", serverName: server_name)
+      end
+
+      # Enable or disable an MCP server (TypeScript SDK parity)
+      #
+      # Toggles an MCP server on or off without removing its configuration.
+      #
+      # @param server_name [String] Name of the MCP server to toggle
+      # @param enabled [Boolean] Whether to enable (true) or disable (false) the server
+      # @return [Hash] Response from the CLI
+      #
+      # @example Enable a server
+      #   protocol.mcp_toggle("my-server", enabled: true)
+      #
+      # @example Disable a server
+      #   protocol.mcp_toggle("my-server", enabled: false)
+      #
+      def mcp_toggle(server_name, enabled:)
+        send_control_request(subtype: "mcp_toggle", serverName: server_name, enabled: enabled)
+      end
+
+      # Initiate OAuth authentication for an MCP server (TypeScript SDK v0.2.52 parity)
+      #
+      # @param server_name [String] Name of the MCP server to authenticate
+      # @return [Hash] Response from the CLI
+      #
+      # @example
+      #   protocol.mcp_authenticate("my-remote-server")
+      #
+      def mcp_authenticate(server_name)
+        send_control_request(subtype: "mcp_authenticate", serverName: server_name)
+      end
+
+      # Clear stored auth credentials for an MCP server (TypeScript SDK v0.2.52 parity)
+      #
+      # @param server_name [String] Name of the MCP server to clear auth for
+      # @return [Hash] Response from the CLI
+      #
+      # @example
+      #   protocol.mcp_clear_auth("my-remote-server")
+      #
+      def mcp_clear_auth(server_name)
+        send_control_request(subtype: "mcp_clear_auth", serverName: server_name)
+      end
+
+      # Stop a running background task (TypeScript SDK parity)
+      #
+      # Sends a stop signal to a running task. A task_notification message
+      # with status 'stopped' will be emitted when the task stops.
+      #
+      # @param task_id [String] The task ID from task_notification events
+      # @return [void]
+      #
+      # @example
+      #   protocol.stop_task("task-123")
+      #
+      def stop_task(task_id)
+        send_control_request(subtype: "stop_task", task_id: task_id)
+      end
+
+      # Apply flag settings (TypeScript SDK v0.2.50 parity)
+      #
+      # Merges the provided settings into the flag settings layer.
+      #
+      # @param settings [Hash] Settings to merge into the flag layer
+      # @return [Hash] Response from the CLI
+      #
+      # @example
+      #   protocol.apply_flag_settings({ "model" => "claude-sonnet-4-5-20250514" })
+      #
+      def apply_flag_settings(settings)
+        send_control_request(subtype: "apply_flag_settings", settings: settings)
+      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 = protocol.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)
+        # Convert servers hash to format expected by CLI
+        servers_config = servers.reject do |_, config|
+          config.is_a?(Hash) && (config[:type] == "sdk" || config["type"] == "sdk")
+        end
+
+        response = send_control_request(subtype: "mcp_set_servers", servers: servers_config)
+
+        McpSetServersResult.new(
+          added: response["added"] || [],
+          removed: response["removed"] || [],
+          errors: response["errors"] || {}
+        )
+      end
+    end
+  end
+end

data/lib/claude_agent/control_protocol/lifecycle.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  class ControlProtocol
+    # Connection lifecycle: start, stop, abort, and the background reader loop.
+    module Lifecycle
+      # Start the control protocol (initialize connection)
+      # @param streaming [Boolean] Whether to use streaming mode
+      # @param prompt [String, nil] Initial prompt for non-streaming mode
+      # @return [Hash, nil] Server info from initialization
+      def start(streaming: true, prompt: nil)
+        logger.info("protocol") { "Starting control protocol (streaming=#{streaming})" }
+        @transport.connect(streaming: streaming, prompt: prompt)
+        @running = true
+
+        # Start background reader thread
+        @reader_thread = Thread.new { reader_loop }
+        logger.debug("protocol") { "Reader thread started" }
+
+        # Always send initialize in streaming mode (Python/TypeScript SDK parity)
+        if streaming
+          @server_info = send_initialize
+          logger.info("protocol") { "Initialize complete" }
+        end
+
+        @server_info
+      end
+
+      # Stop the control protocol
+      # @return [void]
+      def stop
+        logger.info("protocol") { "Stopping control protocol" }
+        @running = false
+        @transport.end_input
+        @reader_thread&.join(5)
+        @transport.close
+      end
+
+      # Abort all pending operations (TypeScript SDK parity)
+      #
+      # This method:
+      # 1. Stops the reader loop
+      # 2. Fails all pending requests with AbortError
+      # 3. Terminates the transport
+      #
+      # @return [void]
+      def abort!
+        @running = false
+
+        # Drain permission queue so reader thread unblocks
+        @permission_queue&.drain!(reason: "Operation aborted")
+
+        # Send cancel requests for pending operations (protocol courtesy)
+        @mutex.synchronize do
+          @pending_requests.each_key do |request_id|
+            begin
+              write_message({ type: "control_cancel_request", request_id: request_id })
+            rescue
+              # Ignore transport errors during abort — fire-and-forget
+            end
+          end
+        end
+
+        # Fail all pending requests
+        @mutex.synchronize do
+          @pending_requests.each_key do |request_id|
+            @pending_results[request_id] = {
+              "subtype" => "error",
+              "error" => "Operation aborted"
+            }
+          end
+          @condition.broadcast
+        end
+
+        # Unblock the consumer and terminate the transport
+        @message_queue.push(:done)
+        @transport.terminate if @transport.respond_to?(:terminate)
+      end
+
+      private
+
+      # Background thread that reads messages and routes them
+      def reader_loop
+        @transport.read_messages do |raw|
+          # Check abort signal on each iteration
+          if @abort_signal&.aborted?
+            @running = false
+            break
+          end
+
+          break unless @running
+
+          if raw["type"] == "control_request"
+            logger.debug("protocol") { "Control request received: #{raw.dig("request", "subtype")}" }
+            handle_control_request(raw)
+          elsif raw["type"] == "control_response"
+            logger.debug("protocol") { "Control response received: #{raw.dig("response", "request_id")}" }
+            handle_control_response(raw)
+          else
+            # SDK message - queue for consumer
+            logger.debug("protocol") { "Queued message: #{raw["type"]}" }
+            @message_queue.push(raw)
+          end
+        end
+      rescue IOError, Errno::EPIPE
+        logger.debug("protocol") { "Reader thread exiting: transport closed" }
+        @running = false
+      rescue AbortError
+        logger.debug("protocol") { "Reader thread exiting: abort signal" }
+        @running = false
+      ensure
+        @message_queue.push(:done)
+      end
+    end
+  end
+end

data/lib/claude_agent/control_protocol/messaging.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  class ControlProtocol
+    # User message sending, iteration, and streaming conversation support.
+    module Messaging
+      # Send a user message
+      # @param content [String, Array] Message content
+      # @param session_id [String] Session ID
+      # @param uuid [String, nil] Message UUID for file checkpointing
+      # @return [void]
+      def send_user_message(content, session_id: "default", uuid: nil)
+        message = {
+          type: "user",
+          message: { role: "user", content: content },
+          session_id: session_id
+        }
+        message[:uuid] = uuid if uuid
+        write_message(message)
+      end
+
+      # Iterate over incoming messages (SDK messages only, not control)
+      # @yield [Message] Parsed message objects
+      # @return [Enumerator] If no block given
+      # @raise [AbortError] If abort signal is triggered
+      def each_message
+        return enum_for(:each_message) unless block_given?
+
+        loop do
+          @abort_signal&.check!
+
+          raw = @message_queue.pop  # blocks until data available
+          break if raw == :done     # sentinel from reader_loop
+
+          begin
+            message = @parser.parse(raw)
+            yield message
+          rescue AbortError
+            raise
+          rescue => e
+            logger.warn("protocol") { "Message parse error: #{e.message}" }
+          end
+        end
+      end
+
+      # Receive messages until a ResultMessage is received
+      # @yield [Message] Parsed message objects
+      # @return [Enumerator] If no block given
+      def receive_response
+        return enum_for(:receive_response) unless block_given?
+
+        each_message do |message|
+          yield message
+          break if message.is_a?(ResultMessage)
+        end
+      end
+
+      # Stream user input from an enumerable (TypeScript SDK parity)
+      #
+      # Sends each message from the input stream to Claude. Messages can be:
+      # - String: Sent as user message content
+      # - Hash: Must have :content key, optionally :session_id and :uuid
+      # - UserMessage: Sent directly
+      #
+      # @param stream [Enumerable] Input stream of messages
+      # @param session_id [String] Default session ID for messages
+      # @return [void]
+      # @raise [AbortError] If abort signal is triggered
+      #
+      # @example With strings
+      #   protocol.stream_input(["Hello", "How are you?"])
+      #
+      # @example With hashes
+      #   protocol.stream_input([
+      #     { content: "Hello", uuid: "msg-1" },
+      #     { content: "Follow up", session_id: "custom" }
+      #   ])
+      #
+      def stream_input(stream, session_id: "default")
+        stream.each do |message|
+          # Check abort signal before each message
+          @abort_signal&.check!
+
+          case message
+          when String
+            send_user_message(message, session_id: session_id)
+          when Hash
+            content = message[:content] || message["content"]
+            msg_session = message[:session_id] || message["session_id"] || session_id
+            uuid = message[:uuid] || message["uuid"]
+            send_user_message(content, session_id: msg_session, uuid: uuid)
+          when UserMessage, UserMessageReplay
+            send_user_message(message.content, session_id: message.session_id || session_id, uuid: message.uuid)
+          else
+            raise ArgumentError, "Unknown message type in stream: #{message.class}"
+          end
+        end
+      end
+
+      # Stream user input and receive responses (TypeScript SDK parity)
+      #
+      # Sends messages from the input stream in a background thread while
+      # yielding responses in the foreground. This enables concurrent input/output.
+      #
+      # @param stream [Enumerable] Input stream of messages
+      # @param session_id [String] Default session ID for messages
+      # @yield [Message] Received messages
+      # @return [Enumerator] If no block given
+      # @raise [AbortError] If abort signal is triggered
+      #
+      # @example
+      #   messages = ["Hello", "Tell me more"]
+      #   protocol.stream_conversation(messages) do |msg|
+      #     case msg
+      #     when ClaudeAgent::AssistantMessage
+      #       puts msg.text
+      #     when ClaudeAgent::ResultMessage
+      #       puts "Done!"
+      #     end
+      #   end
+      #
+      def stream_conversation(stream, session_id: "default", &block)
+        return enum_for(:stream_conversation, stream, session_id: session_id) unless block_given?
+
+        # Track errors from the sender thread
+        sender_error = nil
+
+        # Start sender thread
+        sender_thread = Thread.new do
+          stream_input(stream, session_id: session_id)
+        rescue AbortError => e
+          sender_error = e
+        rescue => e
+          sender_error = e
+          # Don't re-raise here; let the main thread handle it
+        end
+
+        # Yield responses until we get a ResultMessage or error
+        begin
+          each_message do |message|
+            # Check if sender had an error
+            if sender_error
+              raise sender_error if sender_error.is_a?(AbortError)
+
+              raise Error, "Stream input error: #{sender_error.message}"
+            end
+
+            yield message
+            break if message.is_a?(ResultMessage)
+          end
+        ensure
+          # Wait for sender to finish
+          sender_thread.join(1)
+        end
+
+        # Check for sender errors after loop
+        raise sender_error if sender_error.is_a?(AbortError)
+
+        raise Error, "Stream input error: #{sender_error.message}" if sender_error
+      end
+    end
+  end
+end