ask-rails 0.3.0 → 0.11.1

data/lib/ask/rails/audit_log.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ask
+  module Rails
+    # 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", 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.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] 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

data/lib/ask/rails/configuration.rb

@@ -4,7 +4,12 @@ module Ask
   module Rails
     class Configuration
       attr_accessor :default_model, :max_turns, :system_prompt,
-                    :tool_concurrency, :persistence_adapter, :tools
+                    :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"
@@ -13,6 +18,53 @@ module Ask
         @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

data/lib/ask/rails/environment_permissions.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Ask
+  module Rails
+    # Per-environment permission rules for agent tool access.
+    #
+    # Configure within Ask::Rails.configure block:
+    #
+    #   Ask::Rails.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

data/lib/ask/rails/persistence.rb

@@ -2,11 +2,28 @@
 
 module Ask
   module Rails
-    class Persistence
+    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)
@@ -17,8 +34,8 @@ module Ask
         record&.data
       end
 
-      def delete(session_id)
-        model_class.where(session_id: session_id).delete_all
+      def clear
+        model_class.delete_all
       end
 
       def list
@@ -28,7 +45,7 @@ module Ask
       private
 
       def model_class
-        @model_class || (raise "No model class configured. Use Persistence.new(model_class: MyModel)")
+        @model_class || Ask::Rails::Session
       end
     end
   end

data/lib/ask/rails/railtie.rb

@@ -4,7 +4,11 @@ module Ask
   module Rails
     class Railtie < ::Rails::Railtie
       rake_tasks do
-        # Load rake tasks if any
+        desc "Prune old sessions and audit logs based on configuration limits"
+        task ask_rails: :cleanup do
+          count = Ask::Rails.cleanup!
+          puts "Cleaned up #{count || 0} sessions."
+        end
       end
 
       generators do

data/lib/ask/rails/tool.rb

@@ -6,6 +6,35 @@ module Ask
       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

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

@@ -13,10 +13,7 @@ module Ask
           return Ask::Result.error(message: "File not found: #{path}") unless full_path.exist?
 
           content = full_path.read
-          Ask::Result.success(
-            data: { path: path, content: content, size: content.length },
-            metadata: { path: path, size: content.length }
-          )
+          { path: path, content: content, size: content.length }
         end
       end
     end

data/lib/ask/rails/tools/read_routes.rb

@@ -10,10 +10,7 @@ module Ask
           return Ask::Result.error(message: "No routes file found") unless routes_file.exist?
 
           content = routes_file.read
-          Ask::Result.success(
-            data: { content: content },
-            metadata: { size: content.length }
-          )
+          { content: content, size: content.length }
         end
       end
     end

data/lib/ask/rails/tools/route_inspector.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Ask
+  module Rails
+    module Tools
+      class RouteInspector < Ask::Rails::Tool
+        description "Return the parsed Rails route table — every route with its HTTP verb, path, " \
+                     "controller, action, and name. Returns structured data the agent can filter " \
+                     "and reason about, unlike reading the raw routes.rb file."
+
+        param :controller, type: :string, desc: "Filter by controller name (e.g. 'users', 'api/v1/posts')", required: false
+        param :pattern, type: :string, desc: "Filter by path pattern (e.g. 'users', 'admin')", required: false
+        param :verbose, type: :boolean, desc: "Include internal route details (default false)", required: false
+
+        def execute(controller: nil, pattern: nil, verbose: false)
+          return { routes: [], count: 0 } unless defined?(::Rails) && ::Rails.application&.routes
+
+          all_routes = ::Rails.application.routes.routes.map do |route|
+            entry = {
+              verb: verb_for(route),
+              path: route.path.spec.to_s.delete_suffix("(.:format)"),
+              controller: route.defaults[:controller]&.to_s,
+              action: route.defaults[:action]&.to_s,
+              name: route.name&.to_s
+            }
+
+            if verbose
+              entry[:requirements] = route.required_parts.presence
+              entry[:defaults] = route.defaults.except(:controller, :action).presence
+              entry[:constraints] = route.constraints.except(:request_method).presence if route.constraints.any?
+            end
+
+            entry
+          end
+
+          # Remove internal/engine routes unless verbose
+          unless verbose
+            all_routes.reject! { |r| r[:controller].nil? || r[:controller].start_with?("rails/") }
+          end
+
+          # Apply filters
+          all_routes.select! { |r| r[:controller] == controller } if controller
+          all_routes.select! { |r| r[:path].include?(pattern) } if pattern
+
+          {
+            routes: all_routes,
+            count: all_routes.size
+          }
+        end
+
+        private
+
+        def verb_for(route)
+          if route.verb.is_a?(String)
+            route.verb
+          elsif route.verb.respond_to?(:call)
+            # Rails stores verb as a regexp — extract the source
+            source = route.verb.source
+            source.gsub(/[$^\\]/, "").split("|")
+          else
+            "ANY"
+          end
+        rescue
+          "ANY"
+        end
+      end
+    end
+  end
+end

data/lib/ask/rails/tools/run_command.rb

@@ -8,12 +8,50 @@ module Ask
         param :command, type: :string, desc: "Shell command to run", required: true
 
         def execute(command:)
+          check_result = check_command_allowed(command)
+          return check_result if check_result
+
           output = `cd #{rails_root} && #{command} 2>&1`
-          Ask::Result.success(
+          Ask::Result.ok(
             data: { output: output, exit_status: $?.exitstatus },
             metadata: { exit_status: $?.exitstatus }
           )
         end
+
+        private
+
+        def check_command_allowed(command)
+          config = Ask::Rails.configuration
+
+          # Use per-environment rules if configured, fall back to global
+          denied = config.effective_denied_commands
+          allowed = config.effective_allowed_commands
+
+          # 1. Check denied commands first (takes precedence)
+          if denied
+            denied.each do |pattern|
+              if command.match?(pattern)
+                return Ask::Result.error(
+                  message: "Command blocked by deny rule: #{pattern.inspect}"
+                )
+              end
+            end
+          end
+
+          # 2. Check allowed commands (if configured)
+          if allowed
+            matches = allowed.any? { |pattern| command.match?(pattern) }
+            unless matches
+              allowed_desc = allowed.map(&:inspect).join(", ")
+              return Ask::Result.error(
+                message: "Command blocked: does not match any allowed pattern (#{allowed_desc})"
+              )
+            end
+          end
+
+          # 3. No restrictions configured — allow
+          nil
+        end
       end
     end
   end