llama_bot_rails 0.1.11 → 0.1.14

data/lib/llama_bot_rails/agent_auth.rb

@@ -0,0 +1,158 @@
+module LlamaBotRails
+    module AgentAuth
+      extend ActiveSupport::Concern
+      AUTH_SCHEME = "LlamaBot"
+  
+      included do
+        # Add before_action filter to automatically check agent authentication for LlamaBot requests
+
+        if self < ActionController::Base
+          before_action :check_agent_authentication, if: :should_check_agent_auth?
+        end
+        
+        # ------------------------------------------------------------------
+        # 1) For every Devise scope, alias authenticate_<scope>! so it now
+        #    accepts *either* a logged-in browser session OR a valid agent
+        #    token. Existing before/skip filters keep working.
+        # ------------------------------------------------------------------
+        if defined?(Devise)
+          Devise.mappings.keys.each do |scope|
+            scope_filter = :"authenticate_#{scope}!"
+  
+            # Next line is a no-op if the method wasn’t already defined.
+            alias_method scope_filter, :authenticate_user_or_agent! \
+              if method_defined?(scope_filter)
+  
+            # Emit a gentle nudge during development
+            define_method(scope_filter) do |*args|
+              Rails.logger.warn(
+                "#{scope_filter} is now handled by LlamaBotRails::AgentAuth "\
+                "and will be removed in a future version. "\
+                "Use authenticate_user_or_agent! instead."
+              )
+              authenticate_user_or_agent!(*args)
+            end
+          end
+        end
+  
+        # ------------------------------------------------------------------
+        # 2) If Devise isn’t loaded at all, fall back to one alias so apps
+        #    that had authenticate_user! manually defined don’t break.
+        # ------------------------------------------------------------------
+        unless defined?(Devise)
+          # Store the original method if it exists
+          original_authenticate_user = if method_defined?(:authenticate_user!)
+            instance_method(:authenticate_user!)
+          else
+            nil
+          end
+          
+          # Define the new method that calls authenticate_user_or_agent!
+          define_method(:authenticate_user!) do |*args|
+            authenticate_user_or_agent!(*args)
+          end
+        end
+      end
+  
+      # --------------------------------------------------------------------
+      # Public helper: true if the request carries a *valid* agent token
+      # --------------------------------------------------------------------
+      def should_check_agent_auth?
+        # Skip agent authentication entirely if a Devise user is already signed in
+        return false if devise_user_signed_in?
+        
+        # Only check for LlamaBot requests if no Devise user is signed in
+        llama_bot_request?
+      end
+
+      def llama_bot_request?
+        return false unless request&.headers
+        scheme, token = request.headers["Authorization"]&.split(" ", 2)
+        Rails.logger.debug("[LlamaBot] auth header = #{scheme.inspect} #{token&.slice(0,8)}…")
+        return false unless scheme == AUTH_SCHEME && token.present?
+
+        Rails.application.message_verifier(:llamabot_ws).verify(token)
+        true
+      rescue ActiveSupport::MessageVerifier::InvalidSignature
+        false
+      end
+  
+      private
+  
+      # --------------------------------------------------------------------
+      # Automatic check for LlamaBot requests - called by before_action filter
+      # --------------------------------------------------------------------
+      def check_agent_authentication
+        # Check if this controller has LlamaBot-aware actions
+        has_permitted_actions = self.class.respond_to?(:llama_bot_permitted_actions)
+        
+        # Skip if controller doesn't use llama_bot_allow at all
+        return unless has_permitted_actions
+        
+        is_llama_request = llama_bot_request?
+        action_is_whitelisted = self.class.llama_bot_permitted_actions.include?(action_name)
+        
+        if is_llama_request
+          # If it's a LlamaBot request, only allow whitelisted actions
+          unless action_is_whitelisted
+            Rails.logger.warn("[LlamaBot] Action '#{action_name}' isn't white-listed for LlamaBot. To fix this, add `llama_bot_allow :#{action_name}` in your controller.")
+            render json: { error: "Action '#{action_name}' isn't white-listed for LlamaBot. To fix this, add `llama_bot_allow :#{action_name}` in your controller." }, status: :forbidden
+            return
+          end
+          Rails.logger.debug("[[LlamaBot Debug]] Valid LlamaBot request for action '#{action_name}'")
+        elsif action_is_whitelisted
+          # If action requires LlamaBot auth but request isn't a LlamaBot request, reject it
+          Rails.logger.warn("[LlamaBot] Action '#{action_name}' requires LlamaBot authentication, but request is not a valid LlamaBot request.")
+          render json: { error: "Action '#{action_name}' requires LlamaBot authentication" }, status: :forbidden
+          return
+        end
+        
+        # All other cases: non-LlamaBot requests to non-whitelisted actions are allowed
+      end
+
+      # --------------------------------------------------------------------
+      # Unified guard — browser OR agent
+      # --------------------------------------------------------------------
+      def devise_user_signed_in?
+        return false unless defined?(Devise)
+        return false unless request&.env
+        request.env["warden"]&.authenticated?
+      end
+  
+      def authenticate_user_or_agent!(*)
+        return if devise_user_signed_in?  # any logged-in Devise scope
+
+        # 2) LlamaBot token present AND action allowed?
+        if llama_bot_request?
+          scheme, token = request.headers["Authorization"]&.split(" ", 2)
+          data = Rails.application.message_verifier(:llamabot_ws).verify(token)
+
+          allowed = self.class.respond_to?(:llama_bot_permitted_actions) &&
+                  self.class.llama_bot_permitted_actions.include?(action_name)
+
+          if allowed
+            
+            user_object = LlamaBotRails.user_resolver.call(data[:user_id])
+            unless LlamaBotRails.sign_in_method.call(request.env, user_object)
+              head :unauthorized
+            end
+
+            return  # ✅ token + allow-listed action + user found and set properly for rack environment
+          else
+            # ❌ auth token is valid, but the attempted controller action is not added to the whitelist.
+            Rails.logger.warn("[LlamaBot] Action '#{action_name}' isn't white-listed for LlamaBot. To fix this, include LlamaBotRails::ControllerExtensions and add `llama_bot_allow :method` in your controller.")
+            render json: { error: "Action '#{action_name}' isn't white-listed for LlamaBot. To fix this, include LlamaBotRails::ControllerExtensions and add `llama_bot_allow :method` in your controller." }, status: :forbidden
+            return false
+          end
+        end
+
+        # Neither path worked — fall back to Devise's normal behaviour and let Devise handle 401
+        if defined?(Devise) && request&.env
+          request.env["warden"].authenticate!  # 401 or redirect
+        else
+          head :unauthorized
+        end
+      end
+    end
+  end
+  

data/lib/llama_bot_rails/agent_auth_2.rb

@@ -0,0 +1,149 @@
+# lib/llama_bot_rails/agent_auth.rb
+module LlamaBotRails
+    module AgentAuth
+      extend ActiveSupport::Concern
+      AUTH_SCHEME = "LlamaBot"
+  
+      included do
+        # ------------------------------------------------------------------
+        # Use the right callback macro for the including class:
+        #   • Controllers → before_action (old behaviour)
+        #   • ActiveJob   → before_perform  (uses same checker)
+        #   • Anything
+        #     else       → do nothing
+        # ------------------------------------------------------------------
+        if respond_to?(:before_action)
+          before_action :check_agent_authentication, if: :should_check_agent_auth?
+        elsif respond_to?(:before_perform)
+          before_perform :check_agent_authentication
+        end
+  
+        # ------------------------------------------------------------------
+        # 1) For every Devise scope, alias authenticate_<scope>! so it now
+        #    accepts *either* a logged-in browser session OR a valid agent
+        #    token. Existing before/skip filters keep working.
+        # ------------------------------------------------------------------
+        if defined?(Devise)
+          Devise.mappings.keys.each do |scope|
+            scope_filter = :"authenticate_#{scope}!"
+  
+            alias_method scope_filter, :authenticate_user_or_agent! \
+              if method_defined?(scope_filter)
+  
+            define_method(scope_filter) do |*args|
+              Rails.logger.warn(
+                "#{scope_filter} is now handled by LlamaBotRails::AgentAuth "\
+                "and will be removed in a future version. "\
+                "Use authenticate_user_or_agent! instead."
+              )
+              authenticate_user_or_agent!(*args)
+            end
+          end
+        end
+  
+        # ------------------------------------------------------------------
+        # 2) If Devise isn’t loaded at all, fall back to one alias so apps
+        #    that had authenticate_user! manually defined don’t break.
+        # ------------------------------------------------------------------
+        unless defined?(Devise)
+          original_authenticate_user =
+            instance_method(:authenticate_user!) if method_defined?(:authenticate_user!)
+  
+          define_method(:authenticate_user!) do |*args|
+            authenticate_user_or_agent!(*args)
+          end
+        end
+      end
+  
+      # --------------------------------------------------------------------
+      # Public helper: true if the request carries a *valid* agent token
+      # --------------------------------------------------------------------
+      def should_check_agent_auth?
+        # Skip if a Devise user is already signed in
+        return false if devise_user_signed_in?
+        llama_bot_request?
+      end
+  
+      def llama_bot_request?
+        return false unless respond_to?(:request) && request&.headers
+        scheme, token = request.headers["Authorization"]&.split(" ", 2)
+        Rails.logger.debug("[LlamaBot] auth header = #{scheme.inspect} #{token&.slice(0,8)}…")
+        return false unless scheme == AUTH_SCHEME && token.present?
+  
+        Rails.application.message_verifier(:llamabot_ws).verify(token)
+        true
+      rescue ActiveSupport::MessageVerifier::InvalidSignature
+        false
+      end
+  
+      private
+  
+      # --------------------------------------------------------------------
+      # Automatic check for LlamaBot requests
+      # --------------------------------------------------------------------
+      def check_agent_authentication
+        # Jobs don’t have a request object, so skip token logic there
+        return if is_a?(ActiveJob::Base)
+  
+        has_permitted_actions = self.class.respond_to?(:llama_bot_permitted_actions)
+        return unless has_permitted_actions
+  
+        is_llama_request      = llama_bot_request?
+        action_is_whitelisted = self.class.llama_bot_permitted_actions.include?(action_name)
+  
+        if is_llama_request
+          unless action_is_whitelisted
+            Rails.logger.warn("[LlamaBot] Action '#{action_name}' isn't white-listed for LlamaBot.")
+            render json: { error: "Action '#{action_name}' isn't white-listed for LlamaBot." },
+                   status: :forbidden
+          end
+        elsif action_is_whitelisted
+          Rails.logger.warn("[LlamaBot] Action '#{action_name}' requires LlamaBot authentication.")
+          render json: { error: "Action '#{action_name}' requires LlamaBot authentication" },
+                 status: :forbidden
+        end
+      end
+  
+      # --------------------------------------------------------------------
+      # Unified guard — browser OR agent
+      # --------------------------------------------------------------------
+      def devise_user_signed_in?
+        return false unless defined?(Devise)
+        return false unless respond_to?(:request) && request&.env
+        request.env["warden"]&.authenticated?
+      end
+  
+      def authenticate_user_or_agent!(*)
+        return if devise_user_signed_in?             # any logged-in Devise scope
+  
+        if llama_bot_request?
+          scheme, token = request.headers["Authorization"]&.split(" ", 2)
+          data = Rails.application.message_verifier(:llamabot_ws).verify(token)
+  
+          allowed = self.class.respond_to?(:llama_bot_permitted_actions) &&
+                    self.class.llama_bot_permitted_actions.include?(action_name)
+  
+          if allowed
+            user_object = LlamaBotRails.user_resolver.call(data[:user_id])
+            unless LlamaBotRails.sign_in_method.call(request.env, user_object)
+              head :unauthorized
+            end
+            return                                   # ✅ token + allow-listed action
+          else
+            Rails.logger.warn("[LlamaBot] Action '#{action_name}' isn't white-listed for LlamaBot.")
+            render json: { error: "Action '#{action_name}' isn't white-listed for LlamaBot." },
+                   status: :forbidden
+            return false
+          end
+        end
+  
+        # Fall back to Devise or plain 401
+        if defined?(Devise) && respond_to?(:request) && request&.env
+          request.env["warden"].authenticate!
+        else
+          head :unauthorized
+        end
+      end
+    end
+  end
+  

data/lib/llama_bot_rails/agent_state_builder.rb

@@ -6,17 +6,17 @@ module LlamaBotRails
         @context = context
       end
       
-
       # Warning: Types must match exactly or you'll get Pydantic errors. It's brittle - If these don't match exactly what's in nodes.py LangGraph state pydantic types, (For example, having a null value/None type when it should be a string) it will the agent.. 
       # So if it doesn't map state types properly from the frontend, it will break. (must be exactly what's defined here).
       # There won't be an exception thrown -- instead, you'll get an pydantic error message showing up in the BaseMessage content field. (In my case, it was a broken ToolMessage, but serializes from the inherited BaseMessage)
-      def build 
+      def build
         {
-          message: @params[:message], # Rails param from JS/chat UI. This is the user's message to the agent.
-          thread_id: @params[:thread_id], # This is the thread id for the agent. It is used to track the conversation history.
-          api_token: @context[:api_token], # This is an authenticated API token for the agent, so that it can authenticate with us. (It may need access to resources on our Rails app, such as the Rails Console.)
+          message: @params["message"], # Rails param from JS/chat UI. This is the user's message to the agent.
+          thread_id: @params["thread_id"], # This is the thread id for the agent. It is used to track the conversation history.
+          api_token: @context["api_token"], # This is an authenticated API token for the agent, so that it can authenticate with us. (It may need access to resources on our Rails app, such as the Rails Console.)
           agent_prompt: LlamaBotRails.agent_prompt_text, # System prompt instructions for the agent. Can be customized in app/llama_bot/prompts/agent_prompt.txt
-          agent_name: "llamabot" #This routes to the appropriate LangGraph agent as defined in LlamaBot/langgraph.json, and enables us to access different agents on our LlamaBot server.
+          agent_name: "llamabot", #This routes to the appropriate LangGraph agent as defined in LlamaBot/langgraph.json, and enables us to access different agents on our LlamaBot server.
+          available_routes: @context[:available_routes] # This is an array of routes that the agent can access. It is used to track the conversation history.
         }
       end
     end

data/lib/llama_bot_rails/controller_extensions.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+module LlamaBotRails
+    module ControllerExtensions
+      extend ActiveSupport::Concern
+
+      included do
+        # NEW: per-controller class attribute that stores the allow-list
+        class_attribute :llama_bot_permitted_actions,
+                        instance_writer: false,
+                        default: []
+      end
+  
+      class_methods do
+        # Usage: llama_bot_allow :update, :preview
+        def llama_bot_allow(*actions)
+            # normalise to strings so `include?(action_name)` works
+            acts = actions.map(&:to_s)
+          
+            # Check if this specific class has had llama_bot_allow called directly on it
+            if instance_variable_defined?(:@_llama_bot_allow_called)
+              # This class has been configured before, accumulate with existing
+              current_actions = llama_bot_permitted_actions || []
+            else
+              # First time configuring this class, start fresh (ignore inherited values)
+              current_actions = []
+              @_llama_bot_allow_called = true
+            end
+            
+            # Create a new array to ensure inheritance doesn't share state
+            self.llama_bot_permitted_actions = (current_actions + acts).uniq
+          
+            # (optional) keep your global registry if you still need it
+            if defined?(LlamaBotRails.allowed_routes)
+              acts.each { |a| LlamaBotRails.allowed_routes << "#{controller_path}##{a}" }
+            end
+          end
+      end
+    end
+  end
+  

data/lib/llama_bot_rails/engine.rb

@@ -11,8 +11,9 @@ module LlamaBotRails
     end
 
     config.llama_bot_rails = ActiveSupport::OrderedOptions.new
-    config.llama_bot_rails.websocket_url = ENV['LLAMABOT_WEBSOCKET_URL'] || 'ws://llamabot-backend:8000/ws' # <-- default for Docker Compose
-    config.llama_bot_rails.llamabot_api_url = ENV['LLAMABOT_API_URL'] || "http://llamabot-backend:8000" # <-- default for Docker Compose
+
+    config.llama_bot_rails.websocket_url = 'ws://llamabot-backend:8000/ws'
+    config.llama_bot_rails.llamabot_api_url ="http://llamabot-backend:8000"
     config.llama_bot_rails.enable_console_tool = true
     
     initializer "llama_bot_rails.assets.precompile" do |app|
@@ -22,5 +23,10 @@ module LlamaBotRails
     initializer "llama_bot_rails.defaults" do |app|
       app.config.llama_bot_rails.state_builder_class ||= "LlamaBotRails::AgentStateBuilder"
     end
+    
+    initializer "llama_bot_rails.message_verifier" do |app|
+      # Ensure the message verifier is available
+      Rails.application.message_verifier(:llamabot_ws)
+    end
   end
 end

data/lib/llama_bot_rails/llama_bot.rb

@@ -30,6 +30,9 @@ module LlamaBotRails
       http = Net::HTTP.new(uri.host, uri.port)
       
       request = Net::HTTP::Post.new(uri)
+      
+      http.use_ssl = (uri.scheme == "https")
+
       request['Content-Type'] = 'application/json'
       request.body = agent_params.to_json
 

data/lib/llama_bot_rails/railtie.rb

@@ -1,5 +1,11 @@
 module LlamaBotRails
   class Railtie < ::Rails::Railtie
+    initializer "llama_bot.include_controller_extensions" do
+      ActiveSupport.on_load(:action_controller) do
+        include LlamaBotRails::ControllerExtensions
+      end
+    end
+
     config.before_configuration do |app|
       llama_bot_path = Rails.root.join("app", "llama_bot")
 

data/lib/llama_bot_rails/route_helper.rb

@@ -0,0 +1,117 @@
+module LlamaBotRails
+  module RouteHelper
+    # Extracts the description from YARD comments
+    def self.extract_yard_description(comment_text)
+      comment_text.lines.map { |l| l.sub(/^# ?/, '') }
+                  .take_while { |l| !l.strip.start_with?('@') }
+                  .join(' ').strip
+    end
+
+    # Extracts a specific YARD tag from comments
+    def self.extract_yard_tag(comment_text, tag)
+      if match = comment_text.match(/@#{tag} (.+)/)
+        match[1].strip
+      end
+    end
+
+    # Main method: returns XML string of formatted routes for allowed_routes
+    def self.formatted_routes_xml(allowed_routes)
+      xml_routes = ""
+      allowed_routes.each do |route_str|
+        controller, action = route_str.split('#')
+        matching_routes = Rails.application.routes.routes.select do |r|
+          r.defaults[:controller] == controller && r.defaults[:action] == action
+        end
+
+        matching_routes.each do |r|
+          verb = r.verb.to_s.gsub(/[$^]/, '') # Handles both Regexp and String
+          path = r.path.spec.to_s
+          path_params = path.scan(/:\w+/).map { |p| p[1..-1] } # e.g. ["id"]
+
+          # Extract controller class and strong parameters
+          controller_class = "#{controller.camelize}Controller".safe_constantize
+          strong_params = []
+          yard_metadata = {}
+
+          if controller_class
+            # Extract YARD documentation for the action
+            begin
+              method_obj = controller_class.instance_method(action.to_sym)
+              source_location = method_obj.source_location
+              if source_location
+                file_path, line_number = source_location
+                file_lines = File.readlines(file_path)
+                # Look for YARD comments above the method
+                comment_lines = []
+                current_line = line_number - 2 # Start above the method definition
+                while current_line >= 0 && file_lines[current_line].strip.start_with?('#')
+                  comment_lines.unshift(file_lines[current_line].strip)
+                  current_line -= 1
+                end
+                # Parse YARD tags
+                comment_text = comment_lines.join("\n")
+                yard_metadata[:description] = extract_yard_description(comment_text)
+                yard_metadata[:tool_description] = extract_yard_tag(comment_text, 'tool_description')
+                yard_metadata[:example] = extract_yard_tag(comment_text, 'example')
+                yard_metadata[:params] = extract_yard_tag(comment_text, 'params')
+              end
+            rescue => e
+              # Silently continue if YARD parsing fails
+            end
+            # Look for the strong parameter method (e.g., page_params, user_params, etc.)
+            param_method = "#{controller.singularize}_params"
+            if controller_class.private_method_defined?(param_method.to_sym)
+              source_location = controller_class.instance_method(param_method.to_sym).source_location
+              if source_location
+                file_path, line_number = source_location
+                file_lines = File.readlines(file_path)
+                method_lines = []
+                current_line = line_number - 1
+                while current_line < file_lines.length
+                  line = file_lines[current_line].strip
+                  method_lines << line
+                  break if line.include?('end') && !line.include?('permit')
+                  current_line += 1
+                end
+                method_source = method_lines.join(' ')
+                if match = method_source.match(/\.permit\((.*?)\)/)
+                  permit_content = match[1]
+                  strong_params = permit_content.scan(/:(\w+)/).flatten
+                end
+              end
+            end
+            # Also check for any additional params the action might accept
+            additional_params = []
+            case action
+            when 'update', 'create'
+              if controller == 'pages' && action == 'update'
+                additional_params << 'message'
+              end
+            end
+            all_params = (path_params + strong_params + additional_params).uniq
+          else
+            all_params = path_params
+          end
+
+          xml = <<~XML
+            <route>
+              <name>#{route_str}</name>
+              <verb>#{verb}</verb>
+              <path>#{path}</path>
+              <path_params>#{path_params.join(', ')}</path_params>
+              <accepted_params>#{all_params.join(', ')}</accepted_params>
+              <strong_params>#{strong_params.join(', ')}</strong_params>
+              <description>#{yard_metadata[:description]}</description>
+              <tool_description>#{yard_metadata[:tool_description]}</tool_description>
+              <example>#{yard_metadata[:example]}</example>
+              <params>#{yard_metadata[:params]}</params>
+            </route>
+          XML
+
+          xml_routes += xml
+        end
+      end
+      xml_routes
+    end
+  end
+end

data/lib/llama_bot_rails/version.rb

@@ -1,3 +1,3 @@
 module LlamaBotRails
-  VERSION = "0.1.11"
+  VERSION = "0.1.14"
 end

data/lib/llama_bot_rails.rb

@@ -1,35 +1,78 @@
+require "set"                                 # ← you call Set.new
 require "llama_bot_rails/version"
 require "llama_bot_rails/engine"
-
-# require "llama_bot_rails/railtie" # We don't need this, as we're loading the LlamaBot path directly in the engine.
 require "llama_bot_rails/llama_bot"
 require "llama_bot_rails/agent_state_builder"
+require "llama_bot_rails/controller_extensions"
+require "llama_bot_rails/agent_auth"
+require "llama_bot_rails/route_helper"
 
 module LlamaBotRails
+  # ------------------------------------------------------------------
+  # Public configuration
+  # ------------------------------------------------------------------
+
+  # Allow-list of routes the agent may hit
+  mattr_accessor :allowed_routes, default: Set.new
+
+  # Lambda that receives Rack env and returns a user-like object
   class << self
-    def config
-      Rails.application.config.llama_bot_rails
-    end
+    attr_accessor :user_resolver
+    attr_accessor :current_user_resolver
 
-    def agent_prompt_path
-      Rails.root.join("app", "llama_bot", "prompts", "agent_prompt.txt")
+    attr_accessor :sign_in_method
+  end
+  
+  # Default (Devise / Warden); returns nil if Devise absent
+  self.user_resolver = ->(user_id) do
+    # Try to find a User model, fallback to nil if not found
+    # byebug
+    if defined?(Devise)
+      default_scope = Devise.default_scope # e.g., :user
+      user_class = Devise.mappings[default_scope].to
+      user_class.find_by(id: user_id)
+    else
+      Rails.logger.warn("[[LlamaBot]] Implement a user_resolver! in your app to resolve the user from the user_id.")
+      nil
     end
+  end
 
-    def agent_prompt_text
-      if File.exist?(agent_prompt_path)
-        File.read(agent_prompt_path)
-      else
-        "You are LlamaBot, a helpful assistant." #Fallback default.
-      end
+  # Default (Devise / Warden); returns nil if Devise absent
+  self.current_user_resolver = ->(env) do
+    # Try to find a User model, fallback to nil if not found
+    if defined?(Devise)
+      env['warden']&.user
+    else
+      Rails.logger.warn("[[LlamaBot]] Implement a current_user_resolver! in your app to resolve the current user from the environment.")
+      nil
     end
+  end
 
-    def add_instruction_to_agent_prompt!(new_instruction)
-      FileUtils.mkdir_p(agent_prompt_path.dirname)
-      File.write(agent_prompt_path, "\n#{new_instruction}", mode: 'a')
-    end
+  # Lambda that receives Rack env and user_id, and sets the user in the warden session
+  # Default sign-in method is configured for Devise with Warden.
+  self.sign_in_method = ->(env, user) do
+    env['warden']&.set_user(user)
+  end
 
-    def send_agent_message(agent_params)
-      LlamaBot.send_agent_message(agent_params)
-    end
+  # Convenience helper for host-app initializers
+  def self.config = Rails.application.config.llama_bot_rails
+
+  # ------------------------------------------------------------------
+  # Prompt helpers
+  # ------------------------------------------------------------------
+  def self.agent_prompt_path  = Rails.root.join("app", "llama_bot", "prompts", "agent_prompt.txt")
+
+  def self.agent_prompt_text
+    File.exist?(agent_prompt_path) ? File.read(agent_prompt_path) : "You are LlamaBot, a helpful assistant."
   end
-end
+
+  def self.add_instruction_to_agent_prompt!(str)
+    FileUtils.mkdir_p(agent_prompt_path.dirname)
+    File.write(agent_prompt_path, "\n#{str}", mode: "a")
+  end
+
+  # ------------------------------------------------------------------
+  # Bridge to backend service
+  # ------------------------------------------------------------------
+  def self.send_agent_message(params) = LlamaBot.send_agent_message(params)
+end