little_ghost 0.1.0

data/lib/little_ghost/support/loader.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "monitor"
+
+module LittleGhost
+  module Support
+    # Loader finds agents and tools from a conventional application layout. Ruby
+    # files map to constants by path, so applications can add extension classes
+    # without maintaining a manual require list.
+    #
+    #   loader = LittleGhost::Support::Loader.new(root: Dir.pwd)
+    #   loader.setup.eager_load
+    #
+    # Setup is process-serialized, collisions are rejected, and real paths are
+    # checked for symbolic-link escapes. Application load roots are trusted code,
+    # not a sandbox for untrusted files.
+    class Loader
+      DEFAULT_DIRECTORIES = %w[app/agents app/tools].freeze # :nodoc:
+      PROCESS_LOCK = Monitor.new # :nodoc:
+
+      # Application root and configured relative load directories.
+      attr_reader :root, :directories
+
+      # Uses explicit +paths+ or conventional directories beneath +root+.
+      def initialize(paths: nil, root: nil, directories: DEFAULT_DIRECTORIES)
+        @root = root && File.expand_path(root)
+        @directories = Array(directories).map(&:to_s).freeze
+        if @root && @directories.any? { |directory| Pathname.new(directory).absolute? || directory.split(File::SEPARATOR).include?("..") }
+          raise ArgumentError, "application load directories must stay within root"
+        end
+        roots = paths || @directories.map { |directory| File.join(@root || Dir.pwd, directory) }
+        @paths = Array(roots).map { |path| File.expand_path(path) }.uniq.freeze
+        @registry = nil
+        @loaded_constants = {}
+        @setup = false
+      end
+
+      # Installs autoloads for the current registry and returns self.
+      def setup
+        PROCESS_LOCK.synchronize do
+          return self if @setup
+
+          registry.each do |constant_name, path|
+            namespace, name = namespace_for(constant_name)
+            if namespace.const_defined?(name, false) || namespace.autoload?(name)
+              existing = namespace.autoload?(name)
+              next if existing && File.expand_path(existing) == path
+              next if !existing && constant_source_location(constant_name)&.then { |location| File.realpath(location.first) == path }
+              raise ConflictError, "#{constant_name} is already defined"
+            end
+            namespace.autoload(name, path)
+          end
+          @setup = true
+        end
+        self
+      end
+
+      # Loads every registered constant and verifies its defining file.
+      def eager_load
+        PROCESS_LOCK.synchronize do
+          setup
+          registry.each_key do |constant_name|
+            validate_registered_path!(constant_name)
+            constantize(constant_name)
+            @loaded_constants[constant_name] = registry.fetch(constant_name)
+          rescue NameError => error
+            raise unless expected_constant_missing?(error, constant_name)
+            raise ExpectedConstantError, "#{registry.fetch(constant_name)} must define #{constant_name}"
+          end
+        end
+        self
+      end
+
+      # Finds a relative file beneath configured paths, returning its resolved
+      # path or nil.
+      def find(relative_path)
+        clean = clean_path(relative_path)
+        @paths.each do |path_root|
+          candidate = File.expand_path(clean, path_root)
+          next unless inside?(candidate, path_root)
+          next unless File.file?(candidate)
+          real_candidate = File.realpath(candidate)
+          return real_candidate if inside?(real_candidate, real_path_root(path_root))
+        end
+        nil
+      end
+
+      # Finds a relative file or raises LoadError.
+      def fetch(relative_path)
+        find(relative_path) || raise(LoadError, "Could not find #{relative_path} in configured paths")
+      end
+
+      # Reads a relative file using +encoding+.
+      def read(relative_path, encoding: "UTF-8")
+        File.read(fetch(relative_path), encoding:)
+      end
+
+      # Finds resolved paths matching a relative glob without root escapes.
+      def glob(pattern)
+        clean = clean_path(pattern)
+        @paths.flat_map do |path_root|
+          next [] unless Dir.exist?(path_root)
+          real_root = real_path_root(path_root)
+          Dir.glob(File.join(path_root, clean)).filter_map do |candidate|
+            expanded = File.expand_path(candidate)
+            next unless inside?(expanded, path_root)
+            real_candidate = File.realpath(candidate)
+            real_candidate if inside?(real_candidate, real_root)
+          rescue Errno::ENOENT
+            nil
+          end
+        end.uniq.sort
+      end
+
+      # Loads an application constant after installing autoloads.
+      def constant(name)
+        PROCESS_LOCK.synchronize do
+          setup
+          constantize(name.to_s)
+        end
+      rescue NameError => error
+        raise unless expected_constant_missing?(error, name.to_s)
+        raise ExpectedConstantError, "Unknown application constant: #{name}"
+      end
+
+      # Copies registered constant names and resolved paths.
+      def registered_constants
+        registry.dup.freeze
+      end
+
+      # Checks whether +name+ was loaded from its registered source path.
+      def loaded_constant?(name)
+        PROCESS_LOCK.synchronize do
+          path = registry[name.to_s]
+          return false unless path
+
+          names = name.to_s.split("::")
+          leaf = names.pop
+          namespace = names.inject(Object) do |parent, child|
+            break unless parent.const_defined?(child, false)
+
+            parent.const_get(child, false)
+          end
+          autoload_path = namespace&.autoload?(leaf)
+          return File.realpath(autoload_path) == path if autoload_path
+
+          location = constant_source_location(name.to_s)
+          location && File.realpath(location.first) == path
+        end
+      rescue Errno::ENOENT
+        false
+      end
+
+      private
+
+      def registry
+        @registry ||= @paths.each_with_object({}) do |path_root, index|
+          next unless Dir.exist?(path_root)
+
+          Dir.glob(File.join(path_root, "**/*.rb")).sort.each do |path|
+            relative = path.delete_prefix("#{path_root}#{File::SEPARATOR}").delete_suffix(".rb")
+            constant_name = relative.split(File::SEPARATOR).map { |part| camelize(part) }.join("::")
+            expanded = File.realpath(path)
+            unless inside?(expanded, real_path_root(path_root))
+              raise ConflictError, "Autoload path escapes configured root: #{path}"
+            end
+            if index.key?(constant_name) && index[constant_name] != expanded
+              raise ConflictError, "Multiple files map to #{constant_name}: #{index[constant_name]} and #{expanded}"
+            end
+            index[constant_name] = expanded
+          end
+        end.freeze
+      end
+
+      def namespace_for(constant_name)
+        names = constant_name.split("::")
+        name = names.pop
+        namespace = names.inject(Object) do |parent, child|
+          if parent.const_defined?(child, false)
+            value = parent.const_get(child, false)
+            raise ConflictError, "#{parent}::#{child} is not a namespace" unless value.is_a?(Module)
+            value
+          else
+            parent.const_set(child, Module.new)
+          end
+        end
+        [namespace, name]
+      end
+
+      def constantize(name)
+        name.split("::").inject(Object) { |parent, child| parent.const_get(child, false) }
+      end
+
+      def constant_source_location(name)
+        names = name.split("::")
+        leaf = names.pop
+        namespace = Object
+        until names.empty?
+          child = names.shift
+          return if namespace.autoload?(child) || !namespace.const_defined?(child, false)
+
+          namespace = namespace.const_get(child, false)
+        end
+        return if namespace.autoload?(leaf) || !namespace.const_defined?(leaf, false)
+
+        namespace.const_source_location(leaf, false)
+      end
+
+      def camelize(value)
+        value.split("_").map do |part|
+          raise ConflictError, "Invalid autoload path component: #{value}" unless part.match?(/\A[a-z][a-z0-9]*\z/)
+          part[0].upcase + part[1..]
+        end.join
+      end
+
+      def clean_path(value)
+        path = value.to_s
+        raise ArgumentError, "path must be relative" if path.empty? || Pathname.new(path).absolute?
+        raise ArgumentError, "path cannot escape configured roots" if path.split(File::SEPARATOR).include?("..")
+        path
+      end
+
+      def inside?(candidate, path_root)
+        candidate == path_root || candidate.start_with?("#{path_root}#{File::SEPARATOR}")
+      end
+
+      def real_path_root(path_root)
+        resolved = File.realpath(path_root)
+        if @root && !inside?(resolved, File.realpath(@root))
+          raise ConflictError, "Load directory escapes application root: #{path_root}"
+        end
+        resolved
+      end
+
+      def expected_constant_missing?(error, constant_name)
+        names = constant_name.split("::")
+        return false unless error.name.to_s == names.last
+
+        expected_receiver = names[0...-1].inject(Object) { |parent, child| parent.const_get(child, false) }
+        error.receiver.equal?(expected_receiver)
+      rescue ArgumentError, NameError
+        false
+      end
+
+      def validate_registered_path!(constant_name)
+        path = registry.fetch(constant_name)
+        current = File.realpath(path)
+        raise ConflictError, "Autoload path changed after registration: #{path}" unless current == path
+      rescue Errno::ENOENT
+        raise ConflictError, "Autoload path disappeared after registration: #{path}"
+      end
+
+      # Raised when a conventional path collides with an existing constant or
+      # autoload.
+      class ConflictError < Error; end
+
+      # Raised when a loaded file does not define the constant implied by its
+      # path.
+      class ExpectedConstantError < Error; end
+    end
+  end
+end

data/lib/little_ghost/support/output_truncation.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  module Support
+    # OutputTruncation keeps large tool results within a predictable context
+    # budget without breaking UTF-8. Its byte-to-token estimate is deliberately
+    # approximate; use a provider tokenizer when exact accounting is required.
+    module OutputTruncation
+      # Byte estimate used when no provider tokenizer is available.
+      APPROX_BYTES_PER_TOKEN = 4
+
+      module_function
+
+      # Estimates tokens from the UTF-8 byte length of +text+.
+      def approx_token_count(text)
+        approx_tokens_from_byte_count(String(text).bytesize)
+      end
+
+      # Converts a token budget to its approximate byte budget.
+      def approx_bytes_for_tokens(tokens)
+        Integer(tokens) * APPROX_BYTES_PER_TOKEN
+      end
+
+      # Converts bytes to an approximate token count, rounded up.
+      def approx_tokens_from_byte_count(bytes)
+        (Integer(bytes) + APPROX_BYTES_PER_TOKEN - 1) / APPROX_BYTES_PER_TOKEN
+      end
+
+      # Keeps text within budget or produces a middle-truncated
+      # UTF-8 string and the original approximate token count.
+      def truncate_middle_with_token_budget(text, max_tokens)
+        content = utf8_content(text)
+        max_tokens = Integer(max_tokens)
+        max_bytes = approx_bytes_for_tokens(max_tokens)
+        return [content, nil] if max_tokens.positive? && content.bytesize <= max_bytes
+
+        prefix, suffix = split_string(content, max_bytes / 2, max_bytes - (max_bytes / 2))
+        removed_tokens = approx_tokens_from_byte_count([content.bytesize - max_bytes, 0].max)
+        truncated = "#{prefix}…#{removed_tokens} tokens truncated…#{suffix}"
+        [truncated, approx_token_count(content)]
+      end
+
+      def split_string(content, beginning_bytes, end_bytes) # :nodoc:
+        total_bytes = content.bytesize
+        prefix_end = [beginning_bytes, total_bytes].min
+        prefix_end -= 1 while prefix_end.positive? && continuation_byte?(content.getbyte(prefix_end))
+        suffix_start = [total_bytes - end_bytes, 0].max
+        suffix_start += 1 while suffix_start < total_bytes && continuation_byte?(content.getbyte(suffix_start))
+        [content.byteslice(0, prefix_end), content.byteslice(suffix_start, total_bytes - suffix_start)]
+      end
+      private_class_method :split_string
+
+      def continuation_byte?(byte) # :nodoc:
+        byte && (byte & 0xc0) == 0x80
+      end
+      private_class_method :continuation_byte?
+
+      def utf8_content(text) # :nodoc:
+        content = String(text)
+        return content if content.encoding == Encoding::UTF_8 && content.valid_encoding?
+        if content.encoding == Encoding::ASCII_8BIT
+          utf8 = content.dup.force_encoding(Encoding::UTF_8)
+          return utf8 if utf8.valid_encoding?
+        end
+
+        content.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+      end
+      private_class_method :utf8_content
+    end
+  end
+end

data/lib/little_ghost/support/redactor.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  module Support
+    # Redactor removes common credential keys, known secret values, and
+    # secret-shaped strings from nested diagnostic data. It returns a copy and
+    # leaves the caller's value unchanged.
+    #
+    # Redaction is a defense-in-depth aid, not proof that arbitrary
+    # sensitive content is safe to export. Applications should add known secret
+    # values and keep telemetry within an appropriate trust boundary.
+    class Redactor
+      SENSITIVE_KEY = /(authorization|api[_-]?key|credential|password|secret|(?:^|[_-])token(?:$|[_-])|cookie|private[_-]?key)/i # :nodoc:
+      SECRET_PATTERNS = [
+        /\bBearer\s+[A-Za-z0-9._~+\/-]+=*/i,
+        /\b(?:gh[opusr]_[A-Za-z0-9_]{20,}|github_pat_[A-Za-z0-9_]{20,})\b/,
+        /\bAKIA[A-Z0-9]{16}\b/,
+        /\b(?:sk|pk)-[A-Za-z0-9_-]{20,}\b/
+      ].freeze # :nodoc:
+
+      # Adds literal secrets to the built-in patterns. Values shorter than
+      # eight characters are ignored to avoid over-redaction.
+      def initialize(redactions: [], stringify_keys: false)
+        @redactions = Array(redactions).map(&:to_s).reject { |value| value.length < 8 }.uniq.freeze
+        @stringify_keys = stringify_keys
+      end
+
+      # Produces a redacted copy of +value+.
+      def call(value, key: nil)
+        return "[REDACTED]" if key && sensitive_key?(key)
+
+        case value
+        when Hash
+          value.to_h do |child_key, child|
+            output_key = @stringify_keys ? child_key.to_s : child_key
+            [output_key, call(child, key: child_key)]
+          end
+        when Array
+          value.map { |child| call(child) }
+        when String
+          scrub_string(value)
+        else
+          value
+        end
+      end
+
+      # Checks whether +key+ matches a credential-like name.
+      def sensitive_key?(key)
+        SENSITIVE_KEY.match?(normalize_key(key))
+      end
+
+      # Normalizes invalid UTF-8 and replaces configured and common secrets.
+      def scrub_string(value)
+        normalized = value.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "\uFFFD")
+        text = @redactions.reduce(normalized) { |current, secret| current.gsub(secret, "[REDACTED]") }
+        SECRET_PATTERNS.reduce(text) { |current, pattern| current.gsub(pattern, "[REDACTED]") }
+      end
+
+      private
+
+      def normalize_key(key)
+        key.to_s.gsub(/([a-z\d])([A-Z])/, "\\1_\\2").downcase
+      end
+    end
+  end
+end

data/lib/little_ghost/support.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  # Support collects small building blocks for LittleGhost extensions. They are
+  # available to applications that need the same cancellation, loading,
+  # callback, execution, and diagnostic behavior as the framework.
+  module Support
+    module_function
+
+    # Recursively duplicates hashes, arrays, and strings while preserving other
+    # values. Cyclic containers are not supported.
+    def deep_dup(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(key, child), copy| copy[deep_dup(key)] = deep_dup(child) }
+      when Array
+        value.map { |child| deep_dup(child) }
+      when String
+        value.dup
+      else
+        value
+      end
+    end
+  end
+end
+
+require_relative "support/callbacks"
+require_relative "support/cancellation_token"
+require_relative "support/class_attributes"
+require_relative "support/redactor"
+require_relative "support/content_capture"
+require_relative "support/executor"
+require_relative "support/interruptible_stream"
+require_relative "support/loader"