language-operator 0.0.1 → 0.1.30

data/lib/language_operator/agent/safety/ast_validator.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+require 'parser/current'
+
+module LanguageOperator
+  module Agent
+    module Safety
+      # Validates synthesized Ruby code for security before execution
+      # Performs static analysis to detect dangerous method calls
+      class ASTValidator
+        # Gems that are safe to require (allowlist)
+        # These are required for agent execution and are safe
+        ALLOWED_REQUIRES = %w[
+          language_operator
+        ].freeze
+
+        # Dangerous methods that should never be called in synthesized code
+        DANGEROUS_METHODS = %w[
+          system exec spawn fork ` eval instance_eval class_eval module_eval
+          require load autoload require_relative
+          send __send__ public_send method __method__
+          const_set const_get remove_const
+          define_method define_singleton_method
+          undef_method remove_method alias_method
+          exit exit! abort raise fail throw
+          trap at_exit
+          open
+        ].freeze
+
+        # Dangerous constants that should not be accessed
+        DANGEROUS_CONSTANTS = %w[
+          File Dir IO FileUtils Pathname
+          Process Kernel ObjectSpace GC
+          Thread Fiber Mutex ConditionVariable
+          Socket TCPSocket UDPSocket TCPServer UDPServer
+          STDIN STDOUT STDERR
+        ].freeze
+
+        # Safe DSL methods that are allowed in agent definitions
+        SAFE_AGENT_METHODS = %w[
+          agent description persona schedule objectives objective
+          workflow step tool params depends_on prompt
+          constraints budget max_requests rate_limit content_filter
+          output mode webhook as_mcp_server as_chat_endpoint
+        ].freeze
+
+        # Safe DSL methods for tool definitions
+        SAFE_TOOL_METHODS = %w[
+          tool description parameter type required default
+          execute
+        ].freeze
+
+        # Safe helper methods available in execute blocks
+        SAFE_HELPER_METHODS = %w[
+          HTTP Shell
+          validate_url validate_phone validate_email
+          env_required env_get
+          truncate parse_csv
+          error success
+        ].freeze
+
+        # Safe Ruby built-in methods and classes
+        SAFE_BUILTINS = %w[
+          String Array Hash Integer Float Symbol
+          puts print p pp warn
+          true false nil
+          if unless case when then else elsif end
+          while until for break next redo retry return
+          begin rescue ensure
+          lambda proc block_given? yield
+          attr_reader attr_writer attr_accessor
+          private protected public
+          initialize new
+        ].freeze
+
+        class SecurityError < StandardError; end
+
+        def initialize
+          @parser = Parser::CurrentRuby.new
+        end
+
+        # Validate code and raise SecurityError if dangerous methods found
+        # @param code [String] Ruby code to validate
+        # @param file_path [String] Path to file (for error messages)
+        # @raise [SecurityError] if code contains dangerous methods
+        def validate!(code, file_path = '(eval)')
+          ast = parse_code(code, file_path)
+          return if ast.nil? # Empty code is safe
+
+          violations = scan_ast(ast)
+
+          return if violations.empty?
+
+          raise SecurityError, format_violations(violations, file_path)
+        end
+
+        # Validate code and return array of violations (non-raising version)
+        # @param code [String] Ruby code to validate
+        # @param file_path [String] Path to file (for error messages)
+        # @return [Array<Hash>] Array of violation hashes
+        def validate(code, file_path = '(eval)')
+          begin
+            ast = parse_code(code, file_path)
+          rescue SecurityError => e
+            # Convert SecurityError (which wraps Parser::SyntaxError) to violation
+            return [{ type: :syntax_error, message: e.message }]
+          end
+
+          return [] if ast.nil?
+
+          scan_ast(ast)
+        rescue Parser::SyntaxError => e
+          [{ type: :syntax_error, message: e.message }]
+        end
+
+        private
+
+        def parse_code(code, file_path)
+          buffer = Parser::Source::Buffer.new(file_path)
+          buffer.source = code
+          @parser.parse(buffer)
+        rescue Parser::SyntaxError => e
+          raise SecurityError, "Syntax error in #{file_path}: #{e.message}"
+        end
+
+        def scan_ast(node, violations = [])
+          return violations if node.nil?
+
+          case node.type
+          when :send
+            check_method_call(node, violations)
+          when :const
+            check_constant(node, violations)
+          when :gvar
+            check_global_variable(node, violations)
+          when :xstr
+            # Backtick string execution (e.g., `command`)
+            violations << {
+              type: :backtick_execution,
+              location: node.location.line,
+              message: 'Backtick command execution is not allowed'
+            }
+          end
+
+          # Recursively scan all child nodes
+          node.children.each do |child|
+            scan_ast(child, violations) if child.is_a?(Parser::AST::Node)
+          end
+
+          violations
+        end
+
+        def check_method_call(node, violations)
+          receiver, method_name, *args = node.children
+
+          method_str = method_name.to_s
+
+          # Special handling for require - check if it's in the allowlist
+          if %w[require require_relative].include?(method_str)
+            required_gem = extract_require_argument(args)
+
+            # Allow if in the allowlist
+            return if required_gem && ALLOWED_REQUIRES.include?(required_gem)
+
+            # Otherwise, add violation
+            violations << {
+              type: :dangerous_method,
+              method: method_str,
+              location: node.location.line,
+              message: "Dangerous method '#{method_str}' is not allowed"
+            }
+            return
+          end
+
+          # Check for other dangerous methods
+          if DANGEROUS_METHODS.include?(method_str)
+            violations << {
+              type: :dangerous_method,
+              method: method_str,
+              location: node.location.line,
+              message: "Dangerous method '#{method_str}' is not allowed"
+            }
+          end
+
+          # Check for File/Dir/IO operations
+          if receiver && receiver.type == :const
+            const_name = receiver.children[1].to_s
+            if DANGEROUS_CONSTANTS.include?(const_name)
+              violations << {
+                type: :dangerous_constant,
+                constant: const_name,
+                method: method_str,
+                location: node.location.line,
+                message: "Access to #{const_name}.#{method_str} is not allowed"
+              }
+            end
+          end
+
+          # Check for backtick execution (e.g., `command`)
+          # Note: backticks are represented as send with method name :`
+          return unless method_str == '`'
+
+          violations << {
+            type: :backtick_execution,
+            location: node.location.line,
+            message: 'Backtick command execution is not allowed'
+          }
+        end
+
+        def check_constant(node, violations)
+          _, const_name = node.children
+          const_str = const_name.to_s
+
+          # Check for dangerous constants being accessed directly
+          return unless DANGEROUS_CONSTANTS.include?(const_str)
+
+          violations << {
+            type: :dangerous_constant_access,
+            constant: const_str,
+            location: node.location.line,
+            message: "Direct access to #{const_str} constant is not allowed"
+          }
+        end
+
+        def check_global_variable(node, violations)
+          var_name = node.children[0].to_s
+
+          # Block access to dangerous global variables
+          dangerous_globals = %w[$0 $PROGRAM_NAME $LOAD_PATH $: $LOADED_FEATURES $"]
+
+          return unless dangerous_globals.include?(var_name)
+
+          violations << {
+            type: :dangerous_global,
+            variable: var_name,
+            location: node.location.line,
+            message: "Access to global variable #{var_name} is not allowed"
+          }
+        end
+
+        def extract_require_argument(args)
+          # args is an array of AST nodes representing the arguments to require
+          # We're looking for a string literal like 'language_operator' or "language_operator"
+          return nil if args.empty?
+
+          arg_node = args.first
+          return nil unless arg_node
+
+          # Check if it's a string literal (:str node)
+          return arg_node.children[0] if arg_node.type == :str
+
+          # If it's not a string literal (e.g., dynamic require), we can't verify it
+          nil
+        end
+
+        def format_violations(violations, file_path)
+          header = "Security violations detected in #{file_path}:\n\n"
+
+          violation_messages = violations.map do |v|
+            "  Line #{v[:location]}: #{v[:message]}"
+          end
+
+          footer = "\n\nSynthesized code must only use safe DSL methods and approved helpers."
+          footer += "\nSafe methods include: #{SAFE_AGENT_METHODS.join(', ')}, #{SAFE_TOOL_METHODS.join(', ')}"
+          footer += "\nSafe helpers include: HTTP.*, Shell.run, validate_*, env_*"
+
+          header + violation_messages.join("\n") + footer
+        end
+      end
+    end
+  end
+end

data/lib/language_operator/agent/safety/audit_logger.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../../logger'
+require_relative '../../loggable'
+
+module LanguageOperator
+  module Agent
+    module Safety
+      # Audit Logger for safety events
+      #
+      # Logs all safety-related events (blocked requests, budget exceeded, etc.)
+      # for compliance and debugging.
+      #
+      # @example
+      #   audit = AuditLogger.new
+      #   audit.log_blocked_request(reason: 'Budget exceeded', details: {...})
+      class AuditLogger
+        include LanguageOperator::Loggable
+
+        def initialize
+          @audit_log_path = ENV['AUDIT_LOG_PATH'] || '/tmp/langop-audit.jsonl'
+          logger.info('Audit logger initialized', log_path: @audit_log_path)
+        end
+
+        # Log a blocked request
+        #
+        # @param reason [String] Reason for blocking
+        # @param details [Hash] Additional details
+        def log_blocked_request(reason:, details: {})
+          log_event(
+            event_type: 'blocked_request',
+            reason: reason,
+            details: details
+          )
+        end
+
+        # Log a budget event
+        #
+        # @param event [String] Event description
+        # @param details [Hash] Budget details
+        def log_budget_event(event:, details: {})
+          log_event(
+            event_type: 'budget_event',
+            event: event,
+            details: details
+          )
+        end
+
+        # Log a rate limit event
+        #
+        # @param event [String] Event description
+        # @param details [Hash] Rate limit details
+        def log_rate_limit_event(event:, details: {})
+          log_event(
+            event_type: 'rate_limit_event',
+            event: event,
+            details: details
+          )
+        end
+
+        # Log a content filter event
+        #
+        # @param event [String] Event description
+        # @param details [Hash] Filter details
+        def log_content_filter_event(event:, details: {})
+          log_event(
+            event_type: 'content_filter_event',
+            event: event,
+            details: details
+          )
+        end
+
+        private
+
+        def logger_component
+          'Safety::AuditLogger'
+        end
+
+        def log_event(event_data)
+          event = {
+            timestamp: Time.now.utc.iso8601,
+            agent_name: ENV['AGENT_NAME'] || 'unknown',
+            **event_data
+          }
+
+          # Log to standard logger
+          logger.info('Audit event', **event_data)
+
+          # Append to audit log file
+          begin
+            File.open(@audit_log_path, 'a') do |f|
+              f.puts(JSON.generate(event))
+            end
+          rescue StandardError => e
+            logger.error('Failed to write audit log',
+                         error: e.message,
+                         log_path: @audit_log_path)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/language_operator/agent/safety/budget_tracker.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require_relative '../../logger'
+require_relative '../../loggable'
+
+module LanguageOperator
+  module Agent
+    module Safety
+      # Budget Tracker for enforcing cost and token limits
+      #
+      # Tracks cumulative costs and token usage per agent instance
+      # and enforces configured budgets.
+      #
+      # @example
+      #   tracker = BudgetTracker.new(daily_budget: 10.0, hourly_budget: 1.0)
+      #   tracker.check_budget!(estimated_cost: 0.05, estimated_tokens: 500)
+      class BudgetTracker
+        include LanguageOperator::Loggable
+
+        attr_reader :daily_budget, :hourly_budget, :token_budget
+
+        class BudgetExceededError < StandardError; end
+
+        def initialize(daily_budget: nil, hourly_budget: nil, token_budget: nil)
+          @daily_budget = daily_budget&.to_f
+          @hourly_budget = hourly_budget&.to_f
+          @token_budget = token_budget&.to_i
+
+          @daily_spending = 0.0
+          @hourly_spending = 0.0
+          @daily_tokens = 0
+          @hourly_tokens = 0
+
+          @day_start = Time.now
+          @hour_start = Time.now
+
+          logger.info('Budget tracker initialized',
+                      daily_budget: @daily_budget&.round(2),
+                      hourly_budget: @hourly_budget&.round(2),
+                      token_budget: @token_budget)
+        end
+
+        # Check if a request would exceed budget limits
+        #
+        # @param estimated_cost [Float] Estimated cost for the request
+        # @param estimated_tokens [Integer] Estimated token count
+        # @raise [BudgetExceededError] If budget would be exceeded
+        def check_budget!(estimated_cost: 0.0, estimated_tokens: 0)
+          reset_if_needed
+
+          # Check daily budget
+          if @daily_budget && (@daily_spending + estimated_cost) > @daily_budget
+            remaining = [@daily_budget - @daily_spending, 0].max
+            logger.error('Daily budget exceeded',
+                         current: @daily_spending.round(4),
+                         limit: @daily_budget,
+                         remaining: remaining.round(4),
+                         requested: estimated_cost.round(4))
+            raise BudgetExceededError,
+                  "Daily budget exceeded: $#{@daily_spending.round(4)}/$#{@daily_budget} " \
+                  "(requested: $#{estimated_cost.round(4)})"
+          end
+
+          # Check hourly budget
+          if @hourly_budget && (@hourly_spending + estimated_cost) > @hourly_budget
+            remaining = [@hourly_budget - @hourly_spending, 0].max
+            logger.error('Hourly budget exceeded',
+                         current: @hourly_spending.round(4),
+                         limit: @hourly_budget,
+                         remaining: remaining.round(4),
+                         requested: estimated_cost.round(4))
+            raise BudgetExceededError,
+                  "Hourly budget exceeded: $#{@hourly_spending.round(4)}/$#{@hourly_budget} " \
+                  "(requested: $#{estimated_cost.round(4)})"
+          end
+
+          # Check token budget
+          if @token_budget && (@daily_tokens + estimated_tokens) > @token_budget
+            remaining = [@token_budget - @daily_tokens, 0].max
+            logger.error('Token budget exceeded',
+                         current: @daily_tokens,
+                         limit: @token_budget,
+                         remaining: remaining,
+                         requested: estimated_tokens)
+            raise BudgetExceededError,
+                  "Token budget exceeded: #{@daily_tokens}/#{@token_budget} " \
+                  "(requested: #{estimated_tokens})"
+          end
+
+          logger.debug('Budget check passed',
+                       estimated_cost: estimated_cost.round(4),
+                       estimated_tokens: estimated_tokens)
+        end
+
+        # Record actual spending after a request
+        #
+        # @param cost [Float] Actual cost of the request
+        # @param tokens [Integer] Actual token count
+        def record_spending(cost:, tokens:)
+          reset_if_needed
+
+          @daily_spending += cost
+          @hourly_spending += cost
+          @daily_tokens += tokens
+          @hourly_tokens += tokens
+
+          logger.debug('Spending recorded',
+                       cost: cost.round(4),
+                       tokens: tokens,
+                       daily_total: @daily_spending.round(4),
+                       hourly_total: @hourly_spending.round(4),
+                       daily_tokens: @daily_tokens)
+        end
+
+        # Get current budget status
+        #
+        # @return [Hash] Budget status information
+        def status
+          reset_if_needed
+
+          {
+            daily: {
+              spending: @daily_spending.round(4),
+              budget: @daily_budget&.round(2),
+              remaining: @daily_budget ? (@daily_budget - @daily_spending).round(4) : nil,
+              percentage: @daily_budget ? ((@daily_spending / @daily_budget) * 100).round(1) : nil
+            },
+            hourly: {
+              spending: @hourly_spending.round(4),
+              budget: @hourly_budget&.round(2),
+              remaining: @hourly_budget ? (@hourly_budget - @hourly_spending).round(4) : nil,
+              percentage: @hourly_budget ? ((@hourly_spending / @hourly_budget) * 100).round(1) : nil
+            },
+            tokens: {
+              used: @daily_tokens,
+              budget: @token_budget,
+              remaining: @token_budget ? (@token_budget - @daily_tokens) : nil,
+              percentage: @token_budget ? ((@daily_tokens.to_f / @token_budget) * 100).round(1) : nil
+            }
+          }
+        end
+
+        private
+
+        def logger_component
+          'Safety::BudgetTracker'
+        end
+
+        # Reset counters if time periods have elapsed
+        def reset_if_needed
+          now = Time.now
+
+          # Reset daily counters
+          if (now - @day_start) >= 86_400 # 24 hours
+            logger.info('Resetting daily budget counters',
+                        previous_spending: @daily_spending.round(4),
+                        previous_tokens: @daily_tokens)
+            @daily_spending = 0.0
+            @daily_tokens = 0
+            @day_start = now
+          end
+
+          # Reset hourly counters
+          return unless (now - @hour_start) >= 3600 # 1 hour
+
+          logger.debug('Resetting hourly budget counters',
+                       previous_spending: @hourly_spending.round(4))
+          @hourly_spending = 0.0
+          @hourly_tokens = 0
+          @hour_start = now
+        end
+      end
+    end
+  end
+end

data/lib/language_operator/agent/safety/content_filter.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative '../../logger'
+require_relative '../../loggable'
+
+module LanguageOperator
+  module Agent
+    module Safety
+      # Content Filter for pre-prompt and post-response filtering
+      #
+      # Supports pattern matching for blocked keywords and topics.
+      # Can be extended to integrate with moderation APIs.
+      #
+      # @example
+      #   filter = ContentFilter.new(blocked_patterns: ['password', 'secret'])
+      #   filter.check_content!("Here is my password: 12345", direction: :input)
+      class ContentFilter
+        include LanguageOperator::Loggable
+
+        class ContentBlockedError < StandardError; end
+
+        def initialize(blocked_patterns: [], blocked_topics: [], case_sensitive: false)
+          @blocked_patterns = blocked_patterns || []
+          @blocked_topics = blocked_topics || []
+          @case_sensitive = case_sensitive
+
+          logger.info('Content filter initialized',
+                      patterns: @blocked_patterns.length,
+                      topics: @blocked_topics.length,
+                      case_sensitive: @case_sensitive)
+        end
+
+        # Check content for blocked patterns
+        #
+        # @param content [String] Content to check
+        # @param direction [Symbol] :input or :output
+        # @raise [ContentBlockedError] If content contains blocked patterns
+        def check_content!(content, direction: :input)
+          return if @blocked_patterns.empty? && @blocked_topics.empty?
+
+          content_to_check = @case_sensitive ? content : content.downcase
+
+          # Check blocked patterns
+          @blocked_patterns.each do |pattern|
+            pattern_to_match = @case_sensitive ? pattern : pattern.downcase
+            next unless content_to_check.include?(pattern_to_match)
+
+            logger.warn('Blocked pattern detected',
+                        direction: direction,
+                        pattern: pattern,
+                        content_preview: content[0..100])
+            raise ContentBlockedError,
+                  "Content blocked: contains forbidden pattern '#{pattern}' in #{direction}"
+          end
+
+          # Check blocked topics (using regex patterns)
+          @blocked_topics.each do |topic|
+            pattern = @case_sensitive ? Regexp.new(topic) : Regexp.new(topic, Regexp::IGNORECASE)
+            next unless content_to_check.match?(pattern)
+
+            logger.warn('Blocked topic detected',
+                        direction: direction,
+                        topic: topic,
+                        content_preview: content[0..100])
+            raise ContentBlockedError,
+                  "Content blocked: matches forbidden topic '#{topic}' in #{direction}"
+          end
+
+          logger.debug('Content check passed',
+                       direction: direction,
+                       content_length: content.length)
+        end
+
+        # Check if content would be blocked (without raising)
+        #
+        # @param content [String] Content to check
+        # @return [Boolean] True if content would be blocked
+        def blocked?(content)
+          check_content!(content)
+          false
+        rescue ContentBlockedError
+          true
+        end
+
+        private
+
+        def logger_component
+          'Safety::ContentFilter'
+        end
+      end
+    end
+  end
+end