pocketrb 0.1.0 → 0.3.0

data/lib/pocketrb/agent/context.rb

@@ -4,6 +4,7 @@ module Pocketrb
   module Agent
     # Builds context for LLM requests
     class Context
+      # Tool usage guidelines for LLM system prompts
       TOOL_GUIDELINES = <<~PROMPT
         ## Tool Usage Guidelines
 
@@ -18,12 +19,17 @@ module Pocketrb
         - Search memory when the user asks about something you may have learned before
       PROMPT
 
+      # Default agent identity for system prompts
       DEFAULT_IDENTITY = <<~PROMPT
         You are Pocketrb, an AI assistant with access to tools for interacting with files, executing commands, and searching the web.
       PROMPT
 
       attr_reader :system_prompt, :workspace, :skills_summary
 
+      # Initialize a new context builder
+      # @param workspace [Pathname, nil] Path to workspace directory for loading context files
+      # @param system_prompt [String, nil] Custom system prompt (defaults to generated base prompt)
+      # @param skills_summary [String, nil] Summary of available skills to include in prompts
       def initialize(workspace: nil, system_prompt: nil, skills_summary: nil)
         @workspace = workspace
         @skills_summary = skills_summary
@@ -32,6 +38,8 @@ module Pocketrb
 
       private
 
+      # Assemble the base system prompt from identity, tool guidelines, and memory files
+      # @return [String] combined system prompt text
       def build_base_prompt
         parts = []
 
@@ -49,6 +57,9 @@ module Pocketrb
         parts.join("\n\n")
       end
 
+      # Read a file from the workspace directory, returning nil if missing or empty
+      # @param filename [String] name of the file relative to workspace root
+      # @return [String, nil] file contents or nil when unavailable
       def load_workspace_file(filename)
         return nil unless @workspace
 
@@ -68,7 +79,7 @@ module Pocketrb
       # @param history [Array<Message>] Conversation history
       # @param current [String] Current user message
       # @param media [Array<Bus::Media>] Media attachments
-      # @param memory_context [String|nil] Memory context from Memory system
+      # @param memory_context [String, nil] Memory context from Memory system
       # @return [Array<Message>]
       def build_messages(history:, current:, media: nil, memory_context: nil)
         messages = []
@@ -87,6 +98,7 @@ module Pocketrb
 
       # Build messages for continuing after tool execution
       # @param history [Array<Message>] Full history including tool results
+      # @param memory_context [String, nil] Memory context from Memory system
       # @return [Array<Message>]
       def build_continuation(history:, memory_context: nil)
         messages = []
@@ -96,24 +108,32 @@ module Pocketrb
       end
 
       # Update system prompt
+      # @param prompt [String] New system prompt to use
+      # @return [void]
       def update_system_prompt(prompt)
         @system_prompt = prompt
       end
 
       # Add to system prompt
+      # @param content [String] Additional content to append to system prompt
+      # @return [void]
       def append_to_system_prompt(content)
         @system_prompt = "#{@system_prompt}\n\n#{content}"
       end
 
       # Update skills summary
+      # @param summary [String] New skills summary describing available tools/capabilities
+      # @return [void]
       def update_skills_summary(summary)
         @skills_summary = summary
       end
 
       private
 
-      # Strip media from history messages to prevent context bloat
-      # Only the current message should include images
+      # Strip media from history messages to prevent context bloat.
+      # Only the current message should include images.
+      # @param history [Array<Message>] past conversation messages potentially containing media blocks
+      # @return [Array<Message>] new messages with media replaced by text placeholders
       def strip_media_from_history(history)
         history.map do |msg|
           content = msg.content
@@ -149,6 +169,9 @@ module Pocketrb
         end
       end
 
+      # Construct the system message combining prompt, workspace info, skills, and memory
+      # @param memory_context [String, nil] retrieved memory facts to inject into the system message
+      # @return [Message] system-role message for LLM requests
       def build_system_message(memory_context = nil)
         parts = [@system_prompt]
 

data/lib/pocketrb/agent/loop.rb

@@ -10,6 +10,19 @@ module Pocketrb
       attr_reader :bus, :provider, :tools, :sessions, :context, :model, :max_iterations, :workspace, :memory_dir,
                   :memory, :compaction
 
+      # Initialize the agent loop
+      # @param bus [Bus::MessageBus] Message bus for communication
+      # @param provider [Object] LLM provider instance
+      # @param workspace [String, Pathname] Working directory path
+      # @param memory_dir [String, Pathname, nil] Directory for memory and session storage (defaults to workspace)
+      # @param model [String, nil] Model name to use (defaults to provider default)
+      # @param max_iterations [Integer] Maximum tool execution iterations per message
+      # @param system_prompt [String, nil] Custom system prompt (defaults to auto-generated)
+      # @param mcp_endpoint [String, nil] MCP server endpoint URL (currently unused)
+      # @param enable_compaction [Boolean] Whether to enable context compaction
+      # @param compaction_threshold [Integer, nil] Message count threshold for compaction
+      # @param compaction_model [String, nil] Model to use for compaction summaries (defaults to main model)
+      # @param compaction_pressure [Float, nil] Context pressure threshold for compaction (0.0-1.0)
       def initialize(
         bus:,
         provider:,
@@ -20,7 +33,9 @@ module Pocketrb
         system_prompt: nil,
         mcp_endpoint: nil,
         enable_compaction: true,
-        compaction_threshold: nil
+        compaction_threshold: nil,
+        compaction_model: nil,
+        compaction_pressure: nil
       )
         @bus = bus
         @provider = provider
@@ -53,8 +68,10 @@ module Pocketrb
         @compaction = if enable_compaction
                         Compaction.new(
                           provider: @provider,
-                          model: @model,
-                          message_threshold: compaction_threshold
+                          model: compaction_model || @model,
+                          message_threshold: compaction_threshold,
+                          context_window: @provider.context_window(model: @model),
+                          context_pressure: compaction_pressure
                         )
                       end
 
@@ -83,12 +100,13 @@ module Pocketrb
       # Stop the agent loop
       def stop
         @running = false
+        @compaction&.wait_for_compaction(timeout: 10)
         Pocketrb.logger.info("Agent loop stopping")
       end
 
       # Process a single message (synchronous, for direct use)
       # @param msg [Bus::InboundMessage]
-      # @return [Bus::OutboundMessage|nil]
+      # @return [Bus::OutboundMessage, nil]
       def process_message(msg)
         # Update tools context with current channel info for message/send_file tools
         @tools.update_context(
@@ -103,7 +121,14 @@ module Pocketrb
 
         # Compact session history if needed (before building messages)
         if @compaction&.needs_compaction?(session.messages)
-          @compaction.compact_session!(session)
+          @compaction.schedule_compaction(session)
+
+          # Wait for compaction to finish; fall back to synchronous if timeout
+          unless @compaction.wait_for_compaction(timeout: 30)
+            Pocketrb.logger.warn("Background compaction timed out, falling back to synchronous")
+            @compaction.compact_session!(session)
+          end
+
           @sessions.save(session)
         end
 
@@ -165,17 +190,26 @@ module Pocketrb
       end
 
       # Register an additional tool
+      # @param tool [Tools::Base] Tool instance to add to the registry
+      # @return [void]
       def register_tool(tool)
         @tools.register(tool)
       end
 
       # Update the system prompt
+      # @param prompt [String] New system prompt to use for subsequent messages
+      # @return [void]
       def update_system_prompt(prompt)
         @context.update_system_prompt(prompt)
       end
 
       private
 
+      # Execute all tool calls from an LLM response and append results to the message list
+      # @param session [Session::Session] active session to persist tool results into
+      # @param messages [Array<Message>] current message list to extend with assistant and tool messages
+      # @param response [Providers::LLMResponse] LLM response containing tool calls to execute
+      # @return [Array<Message>] updated messages with tool call results appended
       def execute_tool_calls(session, messages, response)
         # Add assistant message with tool calls
         assistant_msg = Providers::Message.assistant(
@@ -231,6 +265,12 @@ module Pocketrb
         messages
       end
 
+      # Publish a tool execution event to the message bus
+      # @param tool_call [Providers::ToolCall] the tool call that was executed
+      # @param result [String, nil] successful execution output, nil on failure
+      # @param error [String, nil] error message if execution failed, nil on success
+      # @param duration_ms [Integer] wall-clock execution time in milliseconds
+      # @return [void]
       def publish_tool_event(tool_call, result, error, duration_ms)
         event = Bus::ToolExecution.new(
           tool_call_id: tool_call.id,
@@ -243,6 +283,12 @@ module Pocketrb
         @bus.publish_tool_event(event)
       end
 
+      # Publish a session state transition event to the message bus
+      # @param session_key [String] identifier of the session changing state
+      # @param from [Symbol] previous state (e.g. :idle, :processing)
+      # @param to [Symbol] new state being transitioned to
+      # @param reason [String, nil] optional explanation for the state change
+      # @return [void]
       def publish_state_change(session_key, from, to, reason = nil)
         event = Bus::StateChange.new(
           session_key: session_key,
@@ -265,6 +311,8 @@ module Pocketrb
       end
 
       # Load skills triggered by a message (for context-aware skill loading)
+      # @param text [String] user message text to match against skill trigger patterns
+      # @return [String] concatenated prompt content from matched skills, empty if none match
       def load_triggered_skills(text)
         triggered = @skills_loader.get_triggered_skills(text)
         return "" if triggered.empty?

data/lib/pocketrb/agent/spawn_tool.rb

@@ -4,14 +4,20 @@ module Pocketrb
   module Agent
     # Tool for spawning subagents
     class SpawnTool < Tools::Base
+      # Tool name
+      # @return [String] Tool name identifier
       def name
         "spawn"
       end
 
+      # Tool description
+      # @return [String] Human-readable description
       def description
         "Spawn a subagent to work on a specific task in the background. Useful for delegating independent work or parallel processing."
       end
 
+      # Tool parameters schema
+      # @return [Hash] JSON schema for tool parameters
       def parameters
         {
           type: "object",
@@ -38,10 +44,18 @@ module Pocketrb
         }
       end
 
+      # Check if tool is available (requires subagent manager)
+      # @return [Boolean] True if subagent manager is available
       def available?
         @context[:subagent_manager] != nil
       end
 
+      # Execute the spawn tool
+      # @param task [String] Task description for the subagent to complete
+      # @param skills [Array<String>] List of skill names to load for the subagent
+      # @param wait [Boolean] Whether to block until subagent completes
+      # @param timeout [Integer] Maximum wait time in seconds when waiting
+      # @return [String] Success or error message
       def execute(task:, skills: [], wait: false, timeout: 300)
         manager = @context[:subagent_manager]
         return error("Subagent spawning not available") unless manager

data/lib/pocketrb/agent/subagent_manager.rb

@@ -8,6 +8,8 @@ module Pocketrb
     class SubagentManager
       attr_reader :active_agents
 
+      # Initialize the subagent manager
+      # @param parent_loop [Loop] Parent agent loop instance that spawns subagents
       def initialize(parent_loop:)
         @parent_loop = parent_loop
         @active_agents = {}
@@ -51,7 +53,7 @@ module Pocketrb
 
       # Get status of a subagent
       # @param agent_id [String]
-      # @return [Hash|nil]
+      # @return [Hash, nil]
       def get_status(agent_id)
         @mutex.synchronize { @active_agents[agent_id]&.dup }
       end
@@ -75,7 +77,7 @@ module Pocketrb
       # Wait for a subagent to complete
       # @param agent_id [String]
       # @param timeout [Integer] Timeout in seconds
-      # @return [String|nil] Result
+      # @return [String, nil] Result
       def wait_for(agent_id, timeout: 300)
         deadline = Time.now + timeout
 
@@ -100,6 +102,10 @@ module Pocketrb
 
       private
 
+      # Execute a subagent lifecycle: create an isolated loop, process the task, and report the result
+      # @param agent_id [String]
+      # @param info [Hash] agent configuration containing :task, :model, :skills, and origin details
+      # @return [void]
       def run_agent(agent_id, info)
         update_status(agent_id, :running)
 
@@ -144,6 +150,11 @@ module Pocketrb
         announce_result(info, "Subagent failed: #{e.message}")
       end
 
+      # Update the tracked status and optional result for a subagent
+      # @param agent_id [String]
+      # @param status [Symbol] new status (e.g. :running, :completed, :failed)
+      # @param result [String, nil] output or error message to store
+      # @return [void]
       def update_status(agent_id, status, result: nil)
         @mutex.synchronize do
           if @active_agents[agent_id]
@@ -154,6 +165,9 @@ module Pocketrb
         end
       end
 
+      # Generate a focused system prompt instructing the subagent on its assigned task
+      # @param info [Hash] agent configuration containing the :task description
+      # @return [String] system prompt for the subagent
       def build_subagent_prompt(info)
         <<~PROMPT
           You are a specialized subagent spawned to complete a specific task.
@@ -169,6 +183,10 @@ module Pocketrb
         PROMPT
       end
 
+      # Load named skills into a subagent loop's system prompt
+      # @param loop [Loop] subagent loop instance to receive skill prompts
+      # @param skill_names [Array<String>] skill names to look up and inject
+      # @return [void]
       def load_skills(loop, skill_names)
         return if skill_names.empty?
 
@@ -181,6 +199,10 @@ module Pocketrb
         loop.context.append_to_system_prompt(skill_content) unless skill_content.empty?
       end
 
+      # Send the subagent's result back to the originating channel via the parent message bus
+      # @param info [Hash] agent configuration with :origin_channel, :origin_chat_id, and :id
+      # @param result [String] completion message to deliver
+      # @return [void]
       def announce_result(info, result)
         outbound = Bus::OutboundMessage.new(
           channel: info[:origin_channel],

data/lib/pocketrb/bus/events.rb

@@ -12,6 +12,13 @@ module Pocketrb
       :media,        # Array<Media> - attached media (images, files, etc.)
       :metadata      # Hash - channel-specific metadata
     ) do
+      # Initialize an inbound message
+      # @param channel [Symbol] Channel identifier (e.g., :cli, :telegram, :discord)
+      # @param sender_id [String] User or system identifier that sent this message
+      # @param chat_id [String] Conversation or thread identifier for session tracking
+      # @param content [String] Text content of the message
+      # @param media [Array<Media>] Array of media attachments (defaults to empty)
+      # @param metadata [Hash] Channel-specific metadata (defaults to empty hash)
       def initialize(channel:, sender_id:, chat_id:, content:, media: [], metadata: {})
         super
       end
@@ -22,8 +29,9 @@ module Pocketrb
       end
 
       # Check if message has media attachments
+      # @return [Boolean] true if media is present
       def has_media?
-        media && !media.empty?
+        !media.nil? && !media.empty?
       end
     end
 
@@ -36,6 +44,13 @@ module Pocketrb
       :reply_to,     # String|nil - message ID to reply to
       :metadata      # Hash - channel-specific options
     ) do
+      # Initialize an outbound message
+      # @param channel [Symbol] Target channel identifier
+      # @param chat_id [String] Target chat or conversation identifier
+      # @param content [String] Text content to send
+      # @param media [Array<Media>] Array of media to attach (defaults to empty)
+      # @param reply_to [String, nil] Message ID to reply to (optional)
+      # @param metadata [Hash] Channel-specific options (defaults to empty hash)
       def initialize(channel:, chat_id:, content:, media: [], reply_to: nil, metadata: {})
         super
       end
@@ -49,14 +64,24 @@ module Pocketrb
       :filename,     # String|nil - original filename
       :data          # String|nil - base64 encoded data (for inline media)
     ) do
+      # Initialize a media attachment
+      # @param type [Symbol] Media type (:image, :file, :audio, or :video)
+      # @param path [String] File system path or URL to the media
+      # @param mime_type [String] MIME type of the media (e.g., "image/png")
+      # @param filename [String, nil] Original filename (optional)
+      # @param data [String, nil] Base64 encoded data for inline media (optional)
       def initialize(type:, path:, mime_type:, filename: nil, data: nil)
         super
       end
 
+      # Check if media is an image type
+      # @return [Boolean] true if type is :image
       def image?
         type == :image
       end
 
+      # Check if media is a file type
+      # @return [Boolean] true if type is :file
       def file?
         type == :file
       end
@@ -71,14 +96,25 @@ module Pocketrb
       :error,        # String|nil - error message if failed
       :duration_ms   # Integer|nil - execution time in milliseconds
     ) do
+      # Initialize a tool execution event
+      # @param tool_call_id [String] LLM-generated identifier linking this execution to the request
+      # @param name [String] Name of the tool being executed
+      # @param arguments [Hash] Arguments passed to the tool
+      # @param result [String, nil] Execution result if successful (optional)
+      # @param error [String, nil] Error message if execution failed (optional)
+      # @param duration_ms [Integer, nil] Execution duration in milliseconds (optional)
       def initialize(tool_call_id:, name:, arguments:, result: nil, error: nil, duration_ms: nil)
         super
       end
 
+      # Check if tool execution succeeded
+      # @return [Boolean] true if no error occurred
       def success?
         error.nil?
       end
 
+      # Check if tool execution failed
+      # @return [Boolean] true if an error occurred
       def failed?
         !success?
       end
@@ -91,6 +127,11 @@ module Pocketrb
       :to_state,     # Symbol - new state
       :reason        # String|nil - reason for change
     ) do
+      # Initialize a state change event
+      # @param session_key [String] Session identifier for the agent
+      # @param from_state [Symbol] Previous state the agent was in
+      # @param to_state [Symbol] New state the agent is transitioning to
+      # @param reason [String, nil] Optional reason for the state change
       def initialize(session_key:, from_state:, to_state:, reason: nil)
         super
       end

data/lib/pocketrb/bus/message_bus.rb

@@ -21,6 +21,9 @@ module Pocketrb
       end
 
       # Publish an inbound message from a channel
+      # @param message [InboundMessage] Message received from a channel
+      # @return [void]
+      # @raise [ArgumentError] if message is not an InboundMessage
       def publish_inbound(message)
         raise ArgumentError, "Expected InboundMessage" unless message.is_a?(InboundMessage)
 
@@ -35,6 +38,9 @@ module Pocketrb
       end
 
       # Publish an outbound message to a channel
+      # @param message [OutboundMessage] Message to send to a channel
+      # @return [void]
+      # @raise [ArgumentError] if message is not an OutboundMessage
       def publish_outbound(message)
         raise ArgumentError, "Expected OutboundMessage" unless message.is_a?(OutboundMessage)
 
@@ -49,6 +55,9 @@ module Pocketrb
       end
 
       # Publish a tool execution event
+      # @param event [ToolExecution] Tool execution event to publish
+      # @return [void]
+      # @raise [ArgumentError] if event is not a ToolExecution
       def publish_tool_event(event)
         raise ArgumentError, "Expected ToolExecution" unless event.is_a?(ToolExecution)
 
@@ -63,6 +72,9 @@ module Pocketrb
       end
 
       # Publish a state change event
+      # @param event [StateChange] State change event to publish
+      # @return [void]
+      # @raise [ArgumentError] if event is not a StateChange
       def publish_state_event(event)
         raise ArgumentError, "Expected StateChange" unless event.is_a?(StateChange)
 
@@ -72,6 +84,11 @@ module Pocketrb
       end
 
       # Subscribe to events
+      # @param type [Symbol] Event type to subscribe to (:inbound, :outbound, :tool, or :state)
+      # @param block [Proc] Block to call when events of this type are published
+      # @yieldparam event [Object] Event object passed to the block
+      # @return [void]
+      # @raise [ArgumentError] if type is not a recognized event type
       def subscribe(type, &block)
         raise ArgumentError, "Unknown event type: #{type}" unless @subscribers.key?(type)
 
@@ -81,6 +98,9 @@ module Pocketrb
       end
 
       # Unsubscribe from events
+      # @param type [Symbol] Event type to unsubscribe from
+      # @param block [Proc] Block to remove from subscribers
+      # @return [void]
       def unsubscribe(type, block)
         @mutex.synchronize do
           @subscribers[type].delete(block)
@@ -88,10 +108,13 @@ module Pocketrb
       end
 
       # Check if queues have pending messages
+      # @return [Boolean] true if the inbound queue is not empty
       def pending_inbound?
         !@inbound.empty?
       end
 
+      # Check if there are pending outbound messages
+      # @return [Boolean] True if outbound queue is not empty
       def pending_outbound?
         !@outbound.empty?
       end
@@ -107,6 +130,10 @@ module Pocketrb
 
       private
 
+      # Notify all subscribers of a given event type
+      # @param type [Symbol] event type (:inbound, :outbound, :tool, :state)
+      # @param event [Object] event object to broadcast
+      # @return [void]
       def notify_subscribers(type, event)
         subscribers = @mutex.synchronize { @subscribers[type].dup }
         subscribers.each do |handler|
@@ -125,20 +152,30 @@ module Pocketrb
           @mutex = Mutex.new
         end
 
+        # Increment a statistic counter
+        # @param key [Symbol] Counter key to increment
+        # @return [void]
         def increment(key)
           @mutex.synchronize { @data[key] += 1 }
         end
 
+        # Retrieve a statistic value
+        # @param key [Symbol] Counter key to retrieve
+        # @return [Integer] Current counter value
         def [](key)
           @mutex.synchronize { @data[key] }
         end
 
+        # Reset all statistics
+        # @return [void]
         def reset!
           @mutex.synchronize do
             @data.transform_values! { 0 }
           end
         end
 
+        # Convert stats to hash
+        # @return [Hash] Stats as hash
         def to_h
           @mutex.synchronize { @data.dup }
         end

data/lib/pocketrb/channels/base.rb

@@ -6,6 +6,9 @@ module Pocketrb
     class Base
       attr_reader :bus, :name
 
+      # Initialize channel adapter
+      # @param bus [Bus::MessageBus] Message bus for publishing and consuming messages
+      # @param name [Symbol, nil] Channel name (defaults to class name)
       def initialize(bus:, name: nil)
         @bus = bus
         @name = name || self.class.name.split("::").last.downcase.to_sym
@@ -25,6 +28,7 @@ module Pocketrb
       end
 
       # Check if channel is running
+      # @return [Boolean] true if the channel is running
       def running?
         @running
       end
@@ -37,12 +41,14 @@ module Pocketrb
       end
 
       # Override in subclasses to send outbound messages
+      # @param message [Bus::OutboundMessage] outbound message to deliver
       def send_message(message)
         raise NotImplementedError
       end
 
       private
 
+      # Consume outbound messages from the bus and dispatch to send_message
       def start_outbound_consumer
         Async do
           while @running
@@ -54,6 +60,13 @@ module Pocketrb
         end
       end
 
+      # Build an inbound message struct for publishing to the bus
+      # @param sender_id [String]
+      # @param chat_id [String] conversation or chat identifier
+      # @param content [String] text content of the message
+      # @param media [Array<Media::Item>] attached media items
+      # @param metadata [Hash] extra channel-specific metadata
+      # @return [Bus::InboundMessage]
       def create_inbound_message(sender_id:, chat_id:, content:, media: [], metadata: {})
         Bus::InboundMessage.new(
           channel: @name,

data/lib/pocketrb/channels/cli.rb

@@ -5,6 +5,9 @@ module Pocketrb
   module Channels
     # Interactive CLI channel
     class CLI < Base
+      # Initialize CLI channel
+      # @param bus [Bus::MessageBus] Message bus for publishing and consuming messages
+      # @param prompt [String] Command prompt string (defaults to "> ")
       def initialize(bus:, prompt: "> ")
         super(bus: bus, name: :cli)
         @prompt = prompt
@@ -13,6 +16,7 @@ module Pocketrb
 
       protected
 
+      # Read user input from stdin and publish inbound messages
       def run_inbound_loop
         Async do
           while @running
@@ -37,6 +41,8 @@ module Pocketrb
         end
       end
 
+      # Print the outbound message content to stdout
+      # @param message [Bus::OutboundMessage] outbound message to display
       def send_message(message)
         @output_mutex.synchronize do
           puts "\n#{format_output(message.content)}\n"
@@ -45,6 +51,8 @@ module Pocketrb
 
       private
 
+      # Read a single line from stdin, returning nil on EOF or interrupt
+      # @return [String, nil]
       def read_input
         line = $stdin.gets
         return nil if line.nil?
@@ -54,6 +62,9 @@ module Pocketrb
         nil
       end
 
+      # Process built-in CLI commands (exit, help, clear, stats)
+      # @param input [String] raw user input to check for commands
+      # @return [Boolean] true if input was a recognized command
       def handle_command(input)
         case input.downcase
         when "exit", "quit", "/exit", "/quit"
@@ -74,6 +85,7 @@ module Pocketrb
         end
       end
 
+      # Display available CLI commands
       def print_help
         puts <<~HELP
 
@@ -86,6 +98,7 @@ module Pocketrb
         HELP
       end
 
+      # Display message bus statistics
       def print_stats
         stats = @bus.stats.to_h
         puts <<~STATS
@@ -98,10 +111,12 @@ module Pocketrb
         STATS
       end
 
+      # Format message content for terminal display
+      # @param content [String, nil] raw message content
+      # @return [String] formatted output string
       def format_output(content)
         return "" if content.nil? || content.empty?
 
-        # Simple formatting - could be enhanced with tty-markdown
         content
       end
     end