language-operator 0.1.59 → 0.1.62

data/lib/language_operator/errors.rb

@@ -1,6 +1,19 @@
 # frozen_string_literal: true
 
 module LanguageOperator
+  # Base exception class for all Language Operator errors
+  class Error < StandardError; end
+
+  # File loading related errors
+  class FileLoadError < Error; end
+  class FileNotFoundError < FileLoadError; end
+  class FilePermissionError < FileLoadError; end
+  class FileSyntaxError < FileLoadError; end
+
+  # Security related errors
+  class SecurityError < Error; end
+  class PathTraversalError < SecurityError; end
+
   # Standardized error formatting module for consistent error messages across tools
   module Errors
     # Resource not found error
@@ -56,5 +69,42 @@ module LanguageOperator
     def self.empty_field(field_name)
       "Error: #{field_name} cannot be empty"
     end
+
+    # File not found error
+    # @param file_path [String] Path to the file that wasn't found
+    # @param context [String] Additional context about what the file is for
+    # @return [String] Formatted error message
+    def self.file_not_found(file_path, context = 'file')
+      "Error: #{context.capitalize} not found at '#{file_path}'. " \
+        'Please check the file path exists and is accessible.'
+    end
+
+    # File permission error
+    # @param file_path [String] Path to the file with permission issues
+    # @param context [String] Additional context about what the file is for
+    # @return [String] Formatted error message
+    def self.file_permission_denied(file_path, context = 'file')
+      "Error: Permission denied reading #{context} '#{file_path}'. " \
+        'Please check file permissions or run with appropriate access rights.'
+    end
+
+    # File syntax error
+    # @param file_path [String] Path to the file with syntax errors
+    # @param original_error [String] Original error message from parser
+    # @param context [String] Additional context about what the file is for
+    # @return [String] Formatted error message
+    def self.file_syntax_error(file_path, original_error, context = 'file')
+      "Error: Syntax error in #{context} '#{file_path}': #{original_error}. " \
+        'Please check the file for valid Ruby syntax.'
+    end
+
+    # Path traversal security error
+    # @param context [String] Context about what operation was attempted
+    # @return [String] Formatted error message
+    def self.path_traversal_blocked(context = 'file operation')
+      "Error: Path traversal attempt blocked during #{context}. " \
+        'File path must be within allowed directories. ' \
+        'Use relative paths or configure LANGOP_ALLOWED_PATHS if needed.'
+    end
   end
 end

data/lib/language_operator/kubernetes/client.rb

@@ -2,6 +2,7 @@
 
 require 'k8s-ruby'
 require 'yaml'
+require_relative '../utils/secure_path'
 
 module LanguageOperator
   module Kubernetes
@@ -30,7 +31,7 @@ module LanguageOperator
 
       def initialize(kubeconfig: nil, context: nil, in_cluster: false)
         @in_cluster = in_cluster
-        @kubeconfig = kubeconfig || ENV.fetch('KUBECONFIG', File.expand_path('~/.kube/config'))
+        @kubeconfig = kubeconfig || ENV.fetch('KUBECONFIG', LanguageOperator::Utils::SecurePath.expand_home_path('.kube/config'))
         @context = context
         @client = build_client
       end
@@ -45,7 +46,11 @@ module LanguageOperator
         nil
       end
 
-      # Get the current namespace from the context
+      # Get the current namespace from the context.
+      # Returns the namespace from service account (in-cluster) or kubeconfig context.
+      # Gracefully handles all filesystem errors and returns nil on failure.
+      #
+      # @return [String, nil] the current namespace, or nil if unable to determine
       def current_namespace
         if @in_cluster
           # In-cluster: read from service account namespace
@@ -56,7 +61,7 @@ module LanguageOperator
           context_obj = config.context(context_name)
           context_obj&.namespace
         end
-      rescue Errno::ENOENT
+      rescue SystemCallError, IOError
         nil
       end
 
@@ -171,8 +176,8 @@ module LanguageOperator
       def operator_version
         deployment = @client.api('apps/v1')
                             .resource('deployments', namespace: 'kube-system')
-                            .get('language-operator')
-        deployment.dig('metadata', 'labels', 'app.kubernetes.io/version') || 'unknown'
+                            .get(Constants::KubernetesLabels::PROJECT_NAME)
+        deployment.dig('metadata', 'labels', Constants::KubernetesLabels::VERSION) || 'unknown'
       rescue K8s::Error::NotFound
         nil
       end
@@ -275,7 +280,7 @@ module LanguageOperator
           'v1'
         when 'deployment', 'statefulset'
           'apps/v1'
-        when 'cronjob'
+        when 'cronjob', 'job'
           'batch/v1'
         else
           'v1'

data/lib/language_operator/kubernetes/resource_builder.rb

@@ -1,37 +1,33 @@
 # frozen_string_literal: true
 
+require_relative '../constants/kubernetes_labels'
+
 module LanguageOperator
   module Kubernetes
     # Builds Kubernetes resource manifests for language-operator
     class ResourceBuilder
       class << self
         # Build a LanguageCluster resource
-        def language_cluster(name, namespace: nil, labels: {})
-          {
-            'apiVersion' => 'langop.io/v1alpha1',
-            'kind' => 'LanguageCluster',
-            'metadata' => {
-              'name' => name,
-              'namespace' => namespace || 'default',
-              'labels' => default_labels.merge(labels)
-            },
-            'spec' => {
-              'namespace' => namespace || name,
-              'resourceQuota' => default_resource_quota,
-              'networkPolicy' => default_network_policy
-            }
+        def language_cluster(name, namespace: nil, domain: nil, labels: {})
+          spec = {
+            'namespace' => namespace || name,
+            'resourceQuota' => default_resource_quota,
+            'networkPolicy' => default_network_policy
           }
+          spec['domain'] = domain if domain && !domain.empty?
+
+          build_resource('LanguageCluster', name, spec, namespace: namespace, labels: labels)
         end
 
         # Build a LanguageAgent resource
-        def language_agent(name, instructions:, cluster: nil, schedule: nil, persona: nil, tools: [], models: [],
+        def language_agent(name, instructions:, cluster: nil, cluster_ref: nil, schedule: nil, persona: nil, tools: [], models: [],
                            mode: nil, workspace: true, labels: {})
           # Determine mode: reactive, scheduled, or autonomous
           spec_mode = mode || (schedule ? 'scheduled' : 'autonomous')
 
           spec = {
             'instructions' => instructions,
-            'mode' => spec_mode,
+            'executionMode' => spec_mode,
             'image' => 'ghcr.io/language-operator/agent:latest'
           }
 
@@ -44,86 +40,41 @@ module LanguageOperator
           # Enable workspace by default for state persistence
           spec['workspace'] = { 'enabled' => workspace } if workspace
 
-          {
-            'apiVersion' => 'langop.io/v1alpha1',
-            'kind' => 'LanguageAgent',
-            'metadata' => {
-              'name' => name,
-              'namespace' => cluster || 'default',
-              'labels' => default_labels.merge(labels)
-            },
-            'spec' => spec
-          }
+          build_resource('LanguageAgent', name, spec, namespace: cluster, cluster_ref: cluster_ref, labels: labels)
         end
 
         # Build a LanguageTool resource
-        def language_tool(name, type:, config: {}, cluster: nil, labels: {})
-          {
-            'apiVersion' => 'langop.io/v1alpha1',
-            'kind' => 'LanguageTool',
-            'metadata' => {
-              'name' => name,
-              'namespace' => cluster || 'default',
-              'labels' => default_labels.merge(labels)
-            },
-            'spec' => {
-              'type' => type,
-              'config' => config
-            }
-          }
+        def language_tool(name, type:, config: {}, cluster: nil, cluster_ref: nil, labels: {})
+          build_resource('LanguageTool', name, {
+                           'type' => type,
+                           'config' => config
+                         }, namespace: cluster, cluster_ref: cluster_ref, labels: labels)
         end
 
         # Build a LanguageModel resource
-        def language_model(name, provider:, model:, endpoint: nil, cluster: nil, labels: {})
+        def language_model(name, provider:, model:, endpoint: nil, cluster: nil, cluster_ref: nil, labels: {})
           spec = {
             'provider' => provider,
             'modelName' => model
           }
           spec['endpoint'] = endpoint if endpoint
 
-          {
-            'apiVersion' => 'langop.io/v1alpha1',
-            'kind' => 'LanguageModel',
-            'metadata' => {
-              'name' => name,
-              'namespace' => cluster || 'default',
-              'labels' => default_labels.merge(labels)
-            },
-            'spec' => spec
-          }
+          build_resource('LanguageModel', name, spec, namespace: cluster, cluster_ref: cluster_ref, labels: labels)
         end
 
         # Build a LanguagePersona resource
         def language_persona(name, description:, tone:, system_prompt:, cluster: nil, labels: {})
-          {
-            'apiVersion' => 'langop.io/v1alpha1',
-            'kind' => 'LanguagePersona',
-            'metadata' => {
-              'name' => name,
-              'namespace' => cluster || 'default',
-              'labels' => default_labels.merge(labels)
-            },
-            'spec' => {
-              'displayName' => name.split('-').map(&:capitalize).join(' '),
-              'description' => description,
-              'tone' => tone,
-              'systemPrompt' => system_prompt
-            }
-          }
+          build_resource('LanguagePersona', name, {
+                           'displayName' => name.split('-').map(&:capitalize).join(' '),
+                           'description' => description,
+                           'tone' => tone,
+                           'systemPrompt' => system_prompt
+                         }, namespace: cluster, labels: labels)
         end
 
         # Build a LanguagePersona resource with full spec control
         def build_persona(name:, spec:, namespace: nil, labels: {})
-          {
-            'apiVersion' => 'langop.io/v1alpha1',
-            'kind' => 'LanguagePersona',
-            'metadata' => {
-              'name' => name,
-              'namespace' => namespace || 'default',
-              'labels' => default_labels.merge(labels)
-            },
-            'spec' => spec
-          }
+          build_resource('LanguagePersona', name, spec, namespace: namespace, labels: labels)
         end
 
         # Build a Kubernetes Service resource for a reactive agent
@@ -141,16 +92,15 @@ module LanguageOperator
               'name' => agent_name,
               'namespace' => namespace || 'default',
               'labels' => default_labels.merge(
-                'app.kubernetes.io/name' => agent_name,
-                'app.kubernetes.io/component' => 'agent'
+                Constants::KubernetesLabels.agent_labels(agent_name)
               ).merge(labels)
             },
             'spec' => {
               'type' => 'ClusterIP',
-              'selector' => {
-                'app.kubernetes.io/name' => agent_name,
-                'app.kubernetes.io/component' => 'agent'
-              },
+              'selector' => Constants::KubernetesLabels.agent_labels(agent_name).slice(
+                Constants::KubernetesLabels::NAME,
+                Constants::KubernetesLabels::COMPONENT
+              ),
               'ports' => [
                 {
                   'name' => 'http',
@@ -165,10 +115,34 @@ module LanguageOperator
 
         private
 
+        # Build a standard language-operator Kubernetes resource
+        #
+        # @param kind [String] The Kubernetes resource kind
+        # @param name [String] The resource name
+        # @param spec [Hash] The resource spec
+        # @param namespace [String, nil] The namespace (defaults to 'default')
+        # @param cluster_ref [String, nil] The cluster reference for lifecycle management
+        # @param labels [Hash] Additional labels to merge with defaults
+        # @return [Hash] Complete Kubernetes resource manifest
+        def build_resource(kind, name, spec, namespace: nil, cluster_ref: nil, labels: {})
+          # Add clusterRef to spec if provided for proper lifecycle management
+          spec = spec.merge('clusterRef' => cluster_ref) if cluster_ref
+          {
+            'apiVersion' => 'langop.io/v1alpha1',
+            'kind' => kind,
+            'metadata' => {
+              'name' => name,
+              'namespace' => namespace || 'default',
+              'labels' => default_labels.merge(labels)
+            },
+            'spec' => spec
+          }
+        end
+
         def default_labels
           {
-            'app.kubernetes.io/managed-by' => 'aictl',
-            'app.kubernetes.io/part-of' => 'language-operator'
+            Constants::KubernetesLabels::MANAGED_BY => Constants::KubernetesLabels::MANAGED_BY_AICTL,
+            Constants::KubernetesLabels::PART_OF => Constants::KubernetesLabels::PROJECT_NAME
           }
         end
 

data/lib/language_operator/templates/schema/agent_dsl_openapi.yaml

@@ -2,7 +2,7 @@
 :openapi: 3.0.3
 :info:
   :title: Language Operator Agent API
-  :version: 0.1.59
+  :version: 0.1.62
   :description: HTTP API endpoints exposed by Language Operator reactive agents
   :contact:
     :name: Language Operator

data/lib/language_operator/templates/schema/agent_dsl_schema.json

@@ -3,7 +3,7 @@
   "$id": "https://github.com/language-operator/language-operator-gem/schema/agent-dsl.json",
   "title": "Language Operator Agent DSL",
   "description": "Schema for defining autonomous AI agents using the Language Operator DSL",
-  "version": "0.1.59",
+  "version": "0.1.62",
   "type": "object",
   "properties": {
     "name": {

data/lib/language_operator/type_coercion.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'lru_redux'
+
 module LanguageOperator
   # Type coercion system for task inputs and outputs
   #
@@ -7,6 +9,12 @@ module LanguageOperator
   # and clear error messages when coercion is not possible. This enables
   # flexible type handling while maintaining type safety.
   #
+  # Performance optimizations:
+  # - Fast-path checks for already-correct types
+  # - Bounded LRU memoization cache for expensive string coercions (prevents memory leaks)
+  # - Pre-compiled regexes for boolean parsing
+  # - Thread-safe cache operations with mutex protection
+  #
   # Supported types:
   # - integer: Coerces String, Integer, Float to Integer
   # - number: Coerces String, Integer, Float to Float
@@ -35,41 +43,113 @@ module LanguageOperator
   #   TypeCoercion.coerce([1, 2], "array")    # => [1, 2]
   #   TypeCoercion.coerce({a: 1}, "array")    # raises ArgumentError
   module TypeCoercion
-    # Coerce a value to the specified type
-    #
-    # @param value [Object] Value to coerce
-    # @param type [String] Target type (see COERCION_RULES for valid types)
-    # @return [Object] Coerced value
-    # @raise [ArgumentError] If coercion fails or type is unknown
-    #
-    # @example
-    #   TypeCoercion.coerce("345", "integer")  # => 345
-    #   TypeCoercion.coerce("true", "boolean") # => true
-    def self.coerce(value, type)
-      case type
-      when 'integer'
-        coerce_integer(value)
-      when 'number'
-        coerce_number(value)
-      when 'string'
-        coerce_string(value)
-      when 'boolean'
-        coerce_boolean(value)
-      when 'array'
-        validate_array(value)
-      when 'hash'
-        validate_hash(value)
-      when 'any'
-        value
-      else
-        raise ArgumentError, "Unknown type: #{type}"
+    # Memory-safe LRU cache for expensive coercions with bounded size to prevent memory leaks
+    # - Cache automatically evicts least recently used entries when limit is reached
+    # - Default cache size: 1000 entries (configurable via TYPE_COERCION_CACHE_SIZE environment variable)
+    # - Thread-safe operations protected by mutex
+    # - Caches both successful and failed coercion attempts to avoid repeated expensive operations
+    DEFAULT_CACHE_SIZE = 1000
+    @cache_size = ENV.fetch('TYPE_COERCION_CACHE_SIZE', DEFAULT_CACHE_SIZE).to_i
+    @coercion_cache = LruRedux::Cache.new(@cache_size)
+    @cache_mutex = Mutex.new
+    @cache_hits = 0
+    @cache_misses = 0
+
+    # Boolean patterns - pre-compiled for performance
+    TRUTHY_PATTERNS = %w[true 1 yes t y].freeze
+    FALSY_PATTERNS = %w[false 0 no f n].freeze
+
+    class << self
+      # Get current cache size limit
+      attr_reader :cache_size
+
+      # Coerce a value to the specified type
+      #
+      # @param value [Object] Value to coerce
+      # @param type [String] Target type (see COERCION_RULES for valid types)
+      # @return [Object] Coerced value
+      # @raise [ArgumentError] If coercion fails or type is unknown
+      #
+      # @example
+      #   TypeCoercion.coerce("345", "integer")  # => 345
+      #   TypeCoercion.coerce("true", "boolean") # => true
+      def coerce(value, type)
+        # Fast path - check cache first for expensive string coercions
+        if value.is_a?(String) && %w[integer number boolean].include?(type)
+          cache_key = [value, type]
+          cached = @cache_mutex.synchronize { @coercion_cache[cache_key] }
+          if cached
+            @cache_hits += 1
+            return cached[:result] if cached[:success]
+
+            raise ArgumentError, cached[:error_message]
+          end
+          @cache_misses += 1
+        end
+
+        # Perform coercion
+        result = case type
+                 when 'integer'
+                   coerce_integer(value)
+                 when 'number'
+                   coerce_number(value)
+                 when 'string'
+                   coerce_string(value)
+                 when 'boolean'
+                   coerce_boolean(value)
+                 when 'array'
+                   validate_array(value)
+                 when 'hash'
+                   validate_hash(value)
+                 when 'any'
+                   value
+                 else
+                   raise ArgumentError, "Unknown type: #{type}"
+                 end
+
+        # Cache successful string coercion results
+        if value.is_a?(String) && %w[integer number boolean].include?(type)
+          cache_entry = { success: true, result: result }
+          @cache_mutex.synchronize { @coercion_cache[[value, type]] = cache_entry }
+        end
+
+        result
+      rescue ArgumentError => e
+        # Cache failed coercion attempts to avoid repeating expensive failures
+        if value.is_a?(String) && %w[integer number boolean].include?(type)
+          cache_entry = { success: false, error_message: e.message }
+          @cache_mutex.synchronize { @coercion_cache[[value, type]] = cache_entry }
+        end
+        raise
+      end
+
+      # Get cache statistics for monitoring
+      def cache_stats
+        @cache_mutex.synchronize do
+          {
+            size: @coercion_cache.count,
+            max_size: @cache_size,
+            hits: @cache_hits,
+            misses: @cache_misses,
+            hit_rate: @cache_hits.zero? ? 0.0 : @cache_hits.to_f / (@cache_hits + @cache_misses)
+          }
+        end
+      end
+
+      # Clear the cache (for testing or memory management)
+      def clear_cache
+        @cache_mutex.synchronize do
+          @coercion_cache.clear
+          @cache_hits = 0
+          @cache_misses = 0
+        end
       end
     end
 
     # Coerce value to Integer
     #
     # Accepts: String, Integer, Float
-    # Coercion: Uses Ruby's Integer() method
+    # Coercion: Uses Ruby's Integer() method with fast-path optimization
     # Errors: Cannot parse as integer
     #
     # @param value [Object] Value to coerce
@@ -82,6 +162,7 @@ module LanguageOperator
     #   coerce_integer(123.0)   # => 123
     #   coerce_integer("abc")   # raises ArgumentError
     def self.coerce_integer(value)
+      # Fast path for already-correct types
       return value if value.is_a?(Integer)
 
       Integer(value)
@@ -92,7 +173,7 @@ module LanguageOperator
     # Coerce value to Float (number)
     #
     # Accepts: String, Integer, Float
-    # Coercion: Uses Ruby's Float() method
+    # Coercion: Uses Ruby's Float() method with fast-path optimization
     # Errors: Cannot parse as number
     #
     # @param value [Object] Value to coerce
@@ -105,7 +186,8 @@ module LanguageOperator
     #   coerce_number(3.14)        # => 3.14
     #   coerce_number("not a num") # raises ArgumentError
     def self.coerce_number(value)
-      return value if value.is_a?(Numeric)
+      # Fast path for already-correct types
+      return value.to_f if value.is_a?(Numeric)
 
       Float(value)
     rescue ArgumentError, TypeError => e
@@ -132,7 +214,7 @@ module LanguageOperator
     # Coerce value to Boolean
     #
     # Accepts: Boolean, String (explicit values only)
-    # Coercion: Case-insensitive string matching
+    # Coercion: Case-insensitive string matching with optimized pattern lookup
     # Truthy: "true", "1", "yes", "t", "y"
     # Falsy: "false", "0", "no", "f", "n"
     # Errors: Ambiguous values (e.g., "maybe", "unknown")
@@ -152,14 +234,16 @@ module LanguageOperator
     #   coerce_boolean("no")      # => false
     #   coerce_boolean("maybe")   # raises ArgumentError
     def self.coerce_boolean(value)
+      # Fast path for already-correct types
       return value if value.is_a?(TrueClass) || value.is_a?(FalseClass)
 
       # Only allow string values for coercion (not integers or other types)
       raise ArgumentError, "Cannot coerce #{value.inspect} to boolean" unless value.is_a?(String)
 
+      # Optimized pattern matching using pre-compiled arrays
       str = value.strip.downcase
-      return true if %w[true 1 yes t y].include?(str)
-      return false if %w[false 0 no f n].include?(str)
+      return true if TRUTHY_PATTERNS.include?(str)
+      return false if FALSY_PATTERNS.include?(str)
 
       raise ArgumentError, "Cannot coerce #{value.inspect} to boolean"
     end

data/lib/language_operator/utils/secure_path.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+module LanguageOperator
+  module Utils
+    # Secure path utilities to prevent path traversal attacks
+    # when expanding user home directory paths
+    class SecurePath
+      # Default fallback directory for untrusted HOME environments
+      DEFAULT_HOME = '/tmp'
+
+      class << self
+        # Securely expand a path relative to user home directory
+        # Prevents path traversal attacks via malicious HOME environment variable
+        #
+        # @param relative_path [String] Path relative to home (e.g., '.kube/config')
+        # @return [String] Safe absolute path
+        def expand_home_path(relative_path)
+          home_dir = secure_home_directory
+          File.join(home_dir, relative_path)
+        end
+
+        # Get user home directory with security validation
+        # Falls back to safe default if HOME environment variable is suspicious
+        #
+        # @return [String] Validated home directory path
+        def secure_home_directory
+          home = ENV.fetch('HOME', DEFAULT_HOME)
+
+          # Validate HOME is safe to use
+          return DEFAULT_HOME unless home_directory_safe?(home)
+
+          home
+        end
+
+        private
+
+        # Validate that a home directory path is safe to use
+        # Prevents path traversal and access to sensitive system directories
+        #
+        # @param path [String] Home directory path to validate
+        # @return [Boolean] true if safe to use
+        def home_directory_safe?(path)
+          # Basic safety checks
+          return false if path.nil? || path.empty?
+          return false if path.include?('../')  # Path traversal
+          return false if path.include?('/..')  # Path traversal
+          return false unless Pathname.new(path).absolute? # Must be absolute
+
+          # Dangerous system paths
+          dangerous_prefixes = [
+            '/etc',        # System configuration
+            '/proc',       # Process information
+            '/sys',        # System information
+            '/dev',        # Device files
+            '/boot',       # Boot files
+            '/root'        # Root user home (should use /root/.kube not accessible via ~)
+          ]
+
+          dangerous_prefixes.each do |prefix|
+            return false if path.start_with?(prefix)
+          end
+
+          # Directory must exist and be readable
+          File.directory?(path) && File.readable?(path)
+        rescue SystemCallError
+          # If we can't check the directory, assume it's unsafe
+          false
+        end
+      end
+    end
+  end
+end

data/lib/language_operator/utils.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module LanguageOperator
+  # Utility modules for common functionality
+  module Utils
+  end
+end