ask-rails-harness 0.1.0

data/lib/ask/rails/harness/audit_log.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ask
+  module Rails
+    module Harness
+      # Append-only audit log for tool executions.
+      #
+      # Every tool call made by an agent is recorded in the +ask_audit_logs+
+      # table with the intent (sanitized params) and outcome (status, timing),
+      # but not the data returned. This gives a trustworthy, queryable record
+      # of what the agent did without becoming a PII liability.
+      #
+      # Sensitive param values (keys matching +password+, +secret+, +token+,
+      # +api_key+, +key+) are automatically redacted before logging.
+      module AuditLog
+        SENSITIVE_KEYS = /\A(password|secret|token|api_key|key|auth_token|access_token)\z/i
+
+        class << self
+          # Log a tool execution event.
+          #
+          # @param session_id [String] The agent session that triggered this call
+          # @param tool_name [String] Name of the tool that ran
+          # @param params [Hash] The parameters passed to the tool (sanitized automatically)
+          # @param result [Ask::Result, Hash, nil] The result returned by the tool
+          # @param error [StandardError, nil] The exception if the tool raised
+          # @param duration_ms [Integer] Wall-clock time for the tool execution
+          # @param user_context [Hash, nil] Who initiated the session (from config)
+          def log(session_id:, tool_name:, params:, result: nil, error: nil, duration_ms:)
+            now = Time.now.utc
+            entry = {
+              session_id: session_id,
+              tool_name: tool_name,
+              params: sanitize_params(params),
+              result_summary: build_summary(tool_name, result, error),
+              status: determine_status(result, error),
+              error_message: determine_error(result, error),
+              duration_ms: duration_ms,
+              user_context: resolve_user_context,
+              environment: environment_name,
+              recorded_at: now,
+              created_at: now,
+              updated_at: now
+            }
+
+            if table_exists?
+              write_entry(entry)
+            end
+
+            # Fire an ActiveSupport notification so host apps can subscribe
+            ActiveSupport::Notifications.instrument("audit_log.ask_rails_harness", entry)
+
+            entry
+          end
+
+          private
+
+          def sanitize_params(params)
+            return {} unless params.is_a?(Hash)
+
+            params.each_with_object({}) do |(key, value), sanitized|
+              if SENSITIVE_KEYS.match?(key.to_s)
+                sanitized[key] = "[REDACTED]"
+              else
+                sanitized[key] = value
+              end
+            end
+          end
+
+          def determine_status(result, error)
+            return "error" if error
+            return "rejected" if result.is_a?(Ask::Result) && (result.error? || result.blocked?)
+            "success"
+          end
+
+          def determine_error(result, error)
+            return error.message if error
+            if result.is_a?(Ask::Result)
+              return result.error.to_s if result.error?
+              return result.content.to_s if result.blocked?
+            end
+            nil
+          end
+
+          def extract_data(result)
+            return nil unless result
+
+            if result.is_a?(Ask::Result)
+              result.content.is_a?(Hash) ? result.content : nil
+            elsif result.is_a?(Hash)
+              result
+            else
+              nil
+            end
+          end
+
+          def build_summary(tool_name, result, error)
+            if error
+              return { error: error.class.name }
+            end
+
+            if result.is_a?(Ask::Result)
+              if result.error?
+                return { error: "rejected: #{result.error.to_s.truncate(200)}" }
+              end
+              if result.blocked?
+                return { error: "blocked: #{result.content.to_s.truncate(200)}" }
+              end
+            end
+
+            data = extract_data(result)
+            return {} unless data
+
+            summary = {}
+            summary[:rows] = data[:rows]&.length if data.key?(:rows)
+            summary[:columns] = data[:columns]&.length if data.key?(:columns)
+            summary[:exit_status] = data[:exit_status] if data.key?(:exit_status)
+            summary[:size] = data[:size] if data.key?(:size)
+            summary[:matched_lines] = data[:matched_lines] if data.key?(:matched_lines)
+            summary[:results] = data[:results]&.length if data.key?(:results)
+            summary[:model] = data[:name] if data.key?(:name)
+            summary
+          end
+
+          def resolve_user_context
+            proc = Ask::Rails::Harness.configuration.current_user
+            return nil unless proc.respond_to?(:call)
+
+            result = proc.call
+            result.is_a?(Hash) ? result : nil
+          rescue StandardError
+            nil
+          end
+
+          def environment_name
+            defined?(::Rails) && ::Rails.respond_to?(:env) ? ::Rails.env.to_s : "unknown"
+          end
+
+          def table_exists?
+            return false unless defined?(ActiveRecord::Base)
+
+            # Only cache the true result — recheck if it was false
+            return @table_exists if @table_exists
+
+            @table_exists = begin
+              conn = ActiveRecord::Base.connection
+              conn.data_source_exists?("ask_audit_logs")
+            rescue StandardError
+              false
+            end
+          end
+
+          def write_entry(entry)
+            # Serialize JSON fields for database storage
+            serialized = entry.dup
+            %i[params result_summary user_context].each do |key|
+              serialized[key] = ::JSON.generate(serialized[key]) if serialized[key].is_a?(Hash)
+            end
+
+            # Use raw SQL to avoid requiring a model class
+            columns = serialized.keys
+            values = columns.map { |col| ActiveRecord::Base.connection.quote(serialized[col]) }
+            ActiveRecord::Base.connection.execute(
+              "INSERT INTO ask_audit_logs (#{columns.join(', ')})
+               VALUES (#{values.join(', ')})"
+            )
+          rescue StandardError => e
+            # Silently fail — audit log should never crash the caller
+            Rails.logger.warn("[ask-rails-harness] Audit log write failed: #{e.message}") if defined?(Rails.logger)
+          end
+
+          # Reset cached table check (useful in tests)
+          public
+
+          def reset_table_check!
+            @table_exists = nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask/rails/harness/auth.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Ask
+  module Rails
+    module Harness
+      # Inclusion module for authenticating the admin chat.
+      #
+      # By default, all ask-rails-harness engine routes are accessible without auth.
+      # To protect them, define a +current_user+ method and set the auth
+      # check in an initializer:
+      #
+      #   Ask::Rails::Harness::Auth.check = -> {
+      #     redirect_to main_app.login_path unless current_user&.admin?
+      #   }
+      #
+      # The proc is evaluated in the controller context, so +redirect_to+,
+      # +current_user+, +session+, etc. are all available.
+      module Auth
+        mattr_accessor :check
+        self.check = nil
+      end
+    end
+  end
+end

data/lib/ask/rails/harness/configuration.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Ask
+  module Rails
+    module Harness
+      class Configuration
+        attr_accessor :default_model, :max_turns, :system_prompt,
+                      :tool_concurrency, :persistence_adapter, :tools,
+                      :current_user, :allowed_commands, :denied_commands,
+                      :max_session_age, :max_sessions
+
+        # @return [Hash{Symbol => EnvironmentPermissions}] per-environment permission rules
+        attr_reader :environments
+
+        def initialize
+          @default_model = "gpt-4o"
+          @max_turns = 25
+          @system_prompt = nil
+          @tool_concurrency = 5
+          @persistence_adapter = nil
+          @tools = []
+          @current_user = nil
+          @allowed_commands = nil
+          @denied_commands = nil
+          @max_session_age = nil
+          @max_sessions = nil
+          @environments = {}
+        end
+
+        # Configure permissions for a specific Rails environment.
+        #
+        #   config.environment :production do |env|
+        #     env.mode = :read_only
+        #     env.allowed_commands = [/^rails routes/]
+        #     env.denied_commands = [/rm/, /dropdb/]
+        #   end
+        #
+        # @param name [Symbol, String] environment name (:production, :development, :staging, etc.)
+        def environment(name)
+          env = EnvironmentPermissions.new
+          yield env
+          @environments[name.to_sym] = env
+        end
+
+        # Resolved allowed commands for the current Rails environment.
+        # Falls back to the global +allowed_commands+ if no per-env config.
+        #
+        # @return [Array<Regexp>, nil]
+        def effective_allowed_commands
+          env = @environments[::Rails.env.to_sym]
+          env&.allowed_commands || @allowed_commands
+        end
+
+        # Resolved denied commands for the current Rails environment.
+        # Falls back to the global +denied_commands+ if no per-env config.
+        #
+        # @return [Array<Regexp>, nil]
+        def effective_denied_commands
+          env = @environments[::Rails.env.to_sym]
+          env&.denied_commands || @denied_commands
+        end
+
+        # Resolved access mode for the current Rails environment.
+        #
+        # @return [Symbol, nil] +:full_access+, +:read_only+, +:ask_before_changes+, or nil
+        def effective_mode
+          env = @environments[::Rails.env.to_sym]
+          env&.mode || nil
+        end
+      end
+    end
+  end
+end

data/lib/ask/rails/harness/engine.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "auth"
+
+module Ask
+  module Rails
+    module Harness
+      class Engine < ::Rails::Engine
+        isolate_namespace Ask::Rails::Harness
+      end
+    end
+  end
+end

data/lib/ask/rails/harness/environment_permissions.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Ask
+  module Rails
+    module Harness
+      # Per-environment permission rules for agent tool access.
+      #
+      # Configure within Ask::Rails::Harness.configure block:
+      #
+      #   Ask::Rails::Harness.configure do |config|
+      #     config.environment :production do |env|
+      #       env.mode = :read_only
+      #       env.allowed_commands = [/^rails routes/, /^rails log/]
+      #       env.denied_commands = [/rm/, /dropdb/]
+      #     end
+      #
+      #     config.environment :development do |env|
+      #       env.mode = :full_access
+      #     end
+      #   end
+      #
+      class EnvironmentPermissions
+        # @return [Symbol, nil] Access mode for ask-agent's Permissions extension
+        #   (:full_access, :read_only, :ask_before_changes)
+        attr_accessor :mode
+
+        # @return [Array<Regexp>, nil] Allowed command patterns for RunCommand
+        attr_accessor :allowed_commands
+
+        # @return [Array<Regexp>, nil] Denied command patterns for RunCommand (takes precedence)
+        attr_accessor :denied_commands
+
+        def initialize
+          @mode = nil
+          @allowed_commands = nil
+          @denied_commands = nil
+        end
+      end
+    end
+  end
+end

data/lib/ask/rails/harness/persistence.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Ask
+  module Rails
+    module Harness
+      class Persistence < ::Ask::State::Adapter
+        def initialize(model_class: nil)
+          @model_class = model_class
+        end
+
+        # State::Adapter contract — set/get/delete
+        # (aliased through save/load for backward compatibility)
+
+        def set(key, value, ttl: nil)
+          save(key, value)
+        end
+
+        def get(key)
+          load(key)
+        end
+
+        def delete(session_id)
+          model_class.where(session_id: session_id).delete_all
+        end
+
+        # Backward-compatible interface (used by old code and list queries)
+
+        def save(session_id, data)
+          record = model_class.find_or_initialize_by(session_id: session_id)
+          record.update!(data: data)
+        end
+
+        def load(session_id)
+          record = model_class.find_by(session_id: session_id)
+          record&.data
+        end
+
+        def clear
+          model_class.delete_all
+        end
+
+        def list
+          model_class.pluck(:session_id)
+        end
+
+        private
+
+        def model_class
+          @model_class || Ask::Rails::Harness::Session
+        end
+      end
+    end
+  end
+end

data/lib/ask/rails/harness/railtie.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Ask
+  module Rails
+    module Harness
+      class Railtie < ::Rails::Railtie
+        rake_tasks do
+          desc "Prune old sessions and audit logs based on configuration limits"
+          task ask_rails_harness: :cleanup do
+            count = Ask::Rails::Harness.cleanup!
+            puts "Cleaned up #{count || 0} sessions."
+          end
+        end
+
+        generators do
+          require_relative "../../../generators/ask/rails/harness/install/install_generator"
+        end
+
+        initializer "ask_rails_harness.configure" do |app|
+          Ask::Rails::Harness.configuration.default_model ||= ENV["ASK_DEFAULT_MODEL"] || "gpt-4o"
+          Ask::Rails::Harness.configuration.max_turns ||= (ENV["ASK_MAX_TURNS"] || 25).to_i
+        end
+
+        initializer "ask_rails_harness.discover_tools", after: :eager_load_most do
+          Ask::Rails::Harness.discover_tools!
+        end
+
+        initializer "ask_rails_harness.discover_services", after: :eager_load_most do
+          Ask::Rails::Harness::ServiceDiscovery.discover!
+        end
+      end
+    end
+  end
+end

data/lib/ask/rails/harness/service_discovery.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Ask
+  module Rails
+    module Harness
+      module ServiceDiscovery
+        SERVICE_GEMS_PATTERN = /\Aask-(?!tools|tools-shell|agent|rails|core|auth|schema|llm)/
+
+        module_function
+
+        def discover!
+          service_gems = Gem.loaded_specs.keys.select { |name| name.match?(SERVICE_GEMS_PATTERN) }
+          contexts = []
+
+          service_gems.each do |name|
+            begin
+              require "#{name.tr("-", "/")}/context"
+              mod = name.split("-").map(&:capitalize).join.constantize
+              contexts << mod if mod.respond_to?(:const_defined?) && mod.const_defined?(:DESCRIPTION)
+            rescue LoadError, NameError
+            end
+          end
+
+          unless contexts.empty?
+            prompt = build_system_prompt(contexts)
+            existing = Ask::Rails::Harness.configuration.system_prompt
+            Ask::Rails::Harness.configuration.system_prompt = [existing, prompt].compact.join("\n\n")
+          end
+
+          contexts
+        end
+
+        def build_system_prompt(contexts)
+          sections = ["## Available Services"]
+
+          contexts.each do |mod|
+            name = mod.respond_to?(:name) ? mod.name.to_s.split("::").last || "Unknown" : "Unknown"
+            sections << "### #{name}"
+            sections << mod::DESCRIPTION if mod.const_defined?(:DESCRIPTION)
+            sections << "Documentation: #{mod::DOCS_URL}" if mod.const_defined?(:DOCS_URL)
+            sections << "Authentication: #{mod::AUTH_HOW}" if mod.const_defined?(:AUTH_HOW)
+            sections << ""
+          end
+
+          sections.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/ask/rails/harness/tool.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Ask
+  module Rails
+    module Harness
+      class Tool < Ask::Tool
+        def rails_root
+          ::Rails.root
+        end
+
+        # Override call to add audit logging around every tool execution.
+        # Logs the intent (sanitized params) and outcome (status, timing),
+        # but not the returned data.
+        def call(args = {}, abort_controller = nil)
+          start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          result = super
+          duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round
+
+          AuditLog.log(
+            session_id: Thread.current[:ask_session_id],
+            tool_name: name,
+            params: args,
+            result: result,
+            duration_ms: duration_ms
+          )
+
+          result
+        end
+
+        # Allow the session to set its ID for audit log correlation.
+        # Called by the agent loop before executing a tool.
+        def self.session_id=(id)
+          Thread.current[:ask_session_id] = id
+        end
+
+        def self.session_id
+          Thread.current[:ask_session_id]
+        end
+      end
+    end
+  end
+end

data/lib/ask/rails/harness/tools/query_database.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Ask
+  module Rails
+    module Harness
+      module Tools
+        class QueryDatabase < Ask::Rails::Harness::Tool
+          description "Run a read-only SQL query against the application database. " \
+                       "Returns columns and rows. Only SELECT queries are allowed in production."
+
+          param :sql,   type: :string, desc: "SQL query (SELECT only in production)", required: true
+          param :limit, type: :integer, desc: "Max rows to return (default 50)", required: false
+
+          WRITE_STATEMENTS = /\A\s*(INSERT|UPDATE|DELETE|DROP|TRUNCATE|ALTER|CREATE|GRANT|REVOKE)\b/i
+
+          def execute(sql:, limit: 50)
+            sql = sql.strip
+
+            if WRITE_STATEMENTS.match?(sql)
+              return Ask::Result.failure(
+                "Only SELECT queries are allowed. Write statements (#{sql.match(WRITE_STATEMENTS)[1]}) are rejected in all environments."
+              )
+            end
+
+            if ::Rails.env.production? && !sql.match?(/\A\s*SELECT\b/i)
+              return Ask::Result.failure(
+                "Only SELECT queries are allowed in the production environment."
+              )
+            end
+
+            pool = ActiveRecord::Base.connection_pool
+            pool.with_connection do |conn|
+              limited_sql = sql.match?(/\bLIMIT\b/i) ? sql : "#{sql.chomp(';')} LIMIT #{limit.to_i}"
+              result = conn.exec_query(limited_sql)
+              columns = result.columns
+              rows = result.rows.first(limit.to_i).map { |row| build_row(row, columns) }
+              {
+                columns: columns,
+                rows: rows,
+                count: rows.size,
+                truncated: result.rows.size > limit.to_i
+              }
+            end
+          rescue ActiveRecord::StatementInvalid => e
+            Ask::Result.failure("SQL error: #{e.message}")
+          rescue ActiveRecord::ConnectionNotEstablished => e
+            Ask::Result.failure("Database not connected: #{e.message}. Verify the database is running and Rails is connected.")
+          end
+
+          private
+
+          def build_row(row, columns)
+            columns.each_with_index.each_with_object({}) do |(col, i), hash|
+              value = row[i]
+              hash[col] = sanitize_value(value)
+            end
+          end
+
+          def sanitize_value(value)
+            return "[BINARY DATA]" if binary_value?(value)
+            return value.iso8601 if value.respond_to?(:iso8601)
+            value
+          end
+
+          def binary_value?(value)
+            value.is_a?(String) && value.encoding == Encoding::ASCII_8BIT && value.bytesize > 0
+          rescue
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask/rails/harness/tools/read_file.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Ask
+  module Rails
+    module Harness
+      module Tools
+        class ReadFile < Ask::Rails::Harness::Tool
+          description "Read a file from the Rails app. Paths are relative to Rails.root."
+
+          param :path, type: :string, desc: "Relative path from Rails.root", required: true
+
+          def execute(path:)
+            full_path = rails_root.join(path)
+            return Ask::Result.error(message: "File not found: #{path}") unless full_path.exist?
+
+            content = full_path.read
+            { path: path, content: content, size: content.length }
+          end
+        end
+      end
+    end
+  end
+end