little_ghost 0.1.0

data/lib/little_ghost/support/callbacks.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  module Support
+    # Callbacks lets extensions prepare, replace, or cancel framework work in a
+    # predictable order. A later callback sees any replacement made earlier in
+    # the chain.
+    #
+    # A callback may return Callbacks.continue, Callbacks.cancel, or
+    # Callbacks.replace. Any other return value means continue. Replacements
+    # become the payload for later callbacks.
+    #
+    # Every decision responds to +continue?+, +cancel?+, and +replace?+. A
+    # cancellation also exposes +reason+; a replacement exposes +value+.
+    # Extensions should depend on these methods rather than a decision's
+    # concrete class.
+    #
+    #   callbacks = LittleGhost::Support::Callbacks.new(:prepare)
+    #   callbacks.on(:prepare) { |payload| Callbacks.replace(payload.merge(debug: true)) }
+    #   decision = callbacks.run(:prepare, {})
+    #   decision.value # => {debug: true}
+    class Callbacks
+      Continue = Data.define do # :nodoc:
+        def continue? = true
+        def cancel? = false
+        def replace? = false
+      end
+      CONTINUE = Continue.new.freeze # :nodoc:
+      Cancel = Data.define(:reason) do # :nodoc:
+        def continue? = false
+        def cancel? = true
+        def replace? = false
+      end
+      Replace = Data.define(:value) do # :nodoc:
+        def continue? = false
+        def cancel? = false
+        def replace? = true
+      end
+
+      class << self
+        # Uses the shared decision whose +continue?+ predicate indicates that
+        # callback processing should proceed.
+        def continue = CONTINUE
+
+        # Creates a decision whose +cancel?+ predicate indicates that callback
+        # processing should stop. The returned value exposes the optional
+        # +reason+.
+        def cancel(reason = nil) = Cancel.new(reason:)
+
+        # Creates a decision whose +replace?+ predicate indicates that later
+        # callbacks should receive +value+.
+        def replace(value) = Replace.new(value:)
+      end
+
+      # Starts an empty chain for the declared callback +names+.
+      def initialize(*names)
+        @callbacks = names.to_h { |name| [name.to_sym, []] }
+        @prepend_counts = names.to_h { |name| [name.to_sym, 0] }
+      end
+
+      # Duplicates callback arrays so subclasses and instances can extend a copy.
+      def initialize_copy(source)
+        super
+        @callbacks = source.instance_variable_get(:@callbacks).transform_values(&:dup)
+        @prepend_counts = source.instance_variable_get(:@prepend_counts).dup
+      end
+
+      # Registers a callable, block, or receiver method name for +name+.
+      def on(name, callable = nil, prepend: false, &block)
+        callback = callable || block
+        unless callback.respond_to?(:call) || callback.is_a?(String) || callback.is_a?(Symbol)
+          raise ArgumentError, "A callback is required"
+        end
+
+        registered = @callbacks.fetch(name.to_sym) { raise ArgumentError, "Unknown callback: #{name}" }
+        unless registered.include?(callback)
+          if prepend
+            registered.unshift(callback)
+            @prepend_counts[name.to_sym] += 1
+          else
+            registered << callback
+          end
+        end
+        self
+      end
+
+      # Combines this chain with +other+ while
+      # preserving prepend ordering.
+      def merge(other)
+        merged = dup
+        other.instance_variable_get(:@callbacks).each do |name, callbacks|
+          prepend_count = other.instance_variable_get(:@prepend_counts).fetch(name)
+          callbacks.first(prepend_count).reverse_each { |callback| merged.on(name, callback, prepend: true) }
+          callbacks.drop(prepend_count).each { |callback| merged.on(name, callback) }
+        end
+        merged
+      end
+
+      # Runs +name+ until callbacks finish or one cancels the chain.
+      #
+      # The returned decision responds to +continue?+, +cancel?+, and
+      # +replace?+. Cancellation decisions expose +reason+, while replacement
+      # decisions expose the final +value+.
+      def run(name, payload, context: nil, receiver: nil)
+        current = payload
+        @callbacks.fetch(name.to_sym) { raise ArgumentError, "Unknown callback: #{name}" }.each do |callback|
+          decision = normalize(invoke(callback, current, context, receiver))
+          case decision
+          when Continue
+            next
+          when Replace
+            current = decision.value
+          else
+            return decision
+          end
+        end
+
+        current.equal?(payload) ? self.class.continue : self.class.replace(current)
+      end
+
+      private
+
+      def invoke(callback, payload, context, receiver)
+        callable = if callback.is_a?(String) || callback.is_a?(Symbol)
+          raise ArgumentError, "A receiver is required for a named callback" unless receiver
+
+          receiver.method(callback)
+        else
+          callback
+        end
+        parameters = callable.respond_to?(:parameters) ? callable.parameters : callable.method(:call).parameters
+        accepts_payload = parameters.any? { |kind, _| %i[req opt rest].include?(kind) }
+        accepts_context = parameters.any? do |kind, name|
+          %i[key keyreq keyrest].include?(kind) && (name == :context || kind == :keyrest)
+        end
+        arguments = accepts_payload ? [payload] : []
+        if receiver && callable.is_a?(Proc)
+          accepts_context ? receiver.instance_exec(*arguments, context:, &callable) : receiver.instance_exec(*arguments, &callable)
+        else
+          accepts_context ? callable.call(*arguments, context:) : callable.call(*arguments)
+        end
+      end
+
+      def normalize(decision)
+        return decision if decision.is_a?(Continue) || decision.is_a?(Cancel) || decision.is_a?(Replace)
+
+        self.class.continue
+      end
+    end
+  end
+end

data/lib/little_ghost/support/cancellation_token.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  module Support
+    # CancellationToken lets related work stop cooperatively without killing its
+    # calling thread. Child tokens make cancellation flow through a run's tree of
+    # work.
+    #
+    # Cancellation is idempotent and flows only downward. Long-running
+    # extensions should call #raise_if_cancelled! at bounded intervals.
+    class CancellationToken
+      # Optionally attaches this token to +parent+.
+      def initialize(parent: nil)
+        @cancelled = false
+        @mutex = Mutex.new
+        @condition = ConditionVariable.new
+        @children = {}
+        @parent = parent
+        parent&.send(:attach, self)
+      end
+
+      # Creates a child cancelled automatically with this token.
+      def child = self.class.new(parent: self)
+
+      # Cancels this token and all currently attached children.
+      def cancel
+        parent, children = @mutex.synchronize do
+          return self if @cancelled
+
+          @cancelled = true
+          @condition.broadcast
+          parent = @parent
+          @parent = nil
+          children = @children.keys
+          @children.clear
+          [parent, children]
+        end
+        parent&.send(:detach, self)
+        children.each(&:cancel)
+        self
+      end
+
+      # Indicates whether cancellation has been requested.
+      def cancelled?
+        @mutex.synchronize { @cancelled }
+      end
+
+      # Raises CancelledError when cancellation has been requested.
+      def raise_if_cancelled!
+        raise CancelledError, "The run was cancelled" if cancelled?
+      end
+
+      # Waits up to +timeout+ seconds for cancellation.
+      def wait(timeout)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + Float(timeout)
+        @mutex.synchronize do
+          until @cancelled
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            break unless remaining.positive?
+
+            @condition.wait(@mutex, remaining)
+          end
+          @cancelled
+        end
+      end
+
+      private
+
+      def attach(child)
+        cancelled = @mutex.synchronize do
+          if @cancelled
+            true
+          else
+            @children[child] = true
+            false
+          end
+        end
+        child.cancel if cancelled
+      end
+
+      def detach(child)
+        @mutex.synchronize { @children.delete(child) }
+      end
+    end
+  end
+end

data/lib/little_ghost/support/class_attributes.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  module Support
+    # ClassAttributes gives framework extension classes small, thread-safe,
+    # inheritable settings. A subclass inherits a value until it assigns its own;
+    # mutable defaults are not duplicated automatically.
+    module ClassAttributes
+      def self.included(base) # :nodoc:
+        base.extend(self)
+      end
+
+      # Defines thread-safe singleton readers and writers for +names+.
+      def class_attribute(*names, default: nil)
+        names.each do |name|
+          unless name.is_a?(String) || name.is_a?(Symbol)
+            raise TypeError, "#{name.inspect} is not a symbol nor a string"
+          end
+
+          name = name.to_sym
+          singleton_class.remove_method(name) if singleton_class.method_defined?(name, false)
+          writer = :"#{name}="
+          singleton_class.remove_method(writer) if singleton_class.method_defined?(writer, false)
+          values = {self => default}
+          mutex = Mutex.new
+          define_singleton_method(name) do
+            found, value = mutex.synchronize { [values.key?(self), values[self]] }
+            return value if found
+
+            superclass.public_send(name)
+          end
+          define_singleton_method(writer) do |value|
+            mutex.synchronize { values[self] = value }
+            value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/little_ghost/support/content_capture.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "json"
+
+module LittleGhost
+  module Support
+    # ContentCapture lets an application opt selected diagnostic content into
+    # telemetry after redaction and scrubbing. Capture stays off until an
+    # application installs an enabled policy.
+    #
+    #   policy = LittleGhost::Support::ContentCapture.new(
+    #     enabled: true,
+    #     max_bytes: 16_384,
+    #     redactions: [ENV.fetch("API_TOKEN")]
+    #   )
+    #   LittleGhost::Instrumentation.capture_content(policy)
+    #
+    # === Security and trust
+    #
+    # Enabling capture may place model input, output, tool definitions, and
+    # exception details into telemetry. Redaction and a custom scrubber reduce
+    # accidental disclosure but are not a security boundary. Configure one
+    # policy per trusted process and apply exporter-side controls as well.
+    class ContentCapture
+      CaptureLimitExceeded = Class.new(StandardError) # :nodoc:
+
+      # Creates a policy that never captures diagnostics.
+      def self.disabled = new(enabled: false)
+
+      # Configures a policy. +max_bytes+ is applied per captured attribute and
+      # +scrubber+ receives already redacted values.
+      def initialize(enabled: false, max_bytes: nil, scrubber: nil, redactions: [])
+        @enabled = enabled == true
+        @max_bytes = Integer(max_bytes) if max_bytes
+        @scrubber = scrubber
+        @redactor = Redactor.new(redactions:, stringify_keys: true)
+        raise ArgumentError, "max_bytes must be at least 64" if @max_bytes && @max_bytes < 64
+        raise ArgumentError, "scrubber must be callable" if @scrubber && !@scrubber.respond_to?(:call)
+      end
+
+      # Produces scrubbed, JSON-encoded diagnostic attributes selected from
+      # +values+, or an empty hash when disabled.
+      def capture(values)
+        return {} unless @enabled && values.is_a?(Hash)
+
+        values.each_with_object({}) do |(key, value), captured|
+          next unless %i[input output exception tool_definitions].include?(key.to_sym)
+
+          captured[:"diagnostic_#{key}"] = if key.to_sym == :tool_definitions
+            capture_tool_definitions(value)
+          else
+            value = structured_output(value) if key.to_sym == :output
+            scrubbed = scrub(value)
+            scrubbed = scrub(@scrubber.call(scrubbed)) if @scrubber
+            truncate(JSON.generate(scrubbed))
+          end
+        rescue JSON::GeneratorError, Encoding::UndefinedConversionError
+          captured[:"diagnostic_#{key}"] = JSON.generate("[UNSERIALIZABLE]")
+        end
+      end
+
+      private
+
+      def capture_tool_definitions(value)
+        unless @max_bytes
+          scrubbed = scrub(value)
+          scrubbed = scrub(@scrubber.call(scrubbed)) if @scrubber
+          return JSON.generate(scrubbed)
+        end
+
+        remaining = [@max_bytes - 32, 1].max
+        scrubbed = bounded_scrub(value, remaining:)
+        scrubbed = bounded_scrub(@scrubber.call(scrubbed), remaining:) if @scrubber
+        encoded = JSON.generate(scrubbed)
+        return encoded if encoded.bytesize <= @max_bytes
+
+        JSON.generate("truncated" => true)
+      rescue CaptureLimitExceeded
+        JSON.generate("truncated" => true)
+      end
+
+      def bounded_scrub(value, remaining:, key: nil)
+        return consume("[REDACTED]", remaining:) if key && @redactor.sensitive_key?(key)
+
+        case value
+        when Hash
+          result = {}
+          value.each do |child_key, child|
+            key_text = consume(child_key.to_s, remaining:)
+            remaining -= key_text.bytesize + 4
+            result[key_text] = bounded_scrub(child, remaining:, key: child_key)
+            remaining -= JSON.generate(result.fetch(key_text)).bytesize
+          end
+          result
+        when Array
+          result = []
+          value.each do |child|
+            captured = bounded_scrub(child, remaining:)
+            result << captured
+            remaining -= JSON.generate(captured).bytesize + 1
+          end
+          result
+        when String
+          raise CaptureLimitExceeded if value.bytesize + 2 > remaining
+
+          consume(@redactor.scrub_string(value), remaining:)
+        when Symbol
+          consume(value.to_s, remaining:)
+        when Numeric, true, false, nil
+          consume(value, remaining:)
+        else
+          consume(value.to_s, remaining:)
+        end
+      end
+
+      def consume(value, remaining:)
+        raise CaptureLimitExceeded if JSON.generate(value).bytesize > remaining
+
+        value
+      end
+
+      def scrub(value, key = nil)
+        @redactor.call(value, key:)
+      end
+
+      def structured_output(value)
+        return value unless value.is_a?(String)
+
+        parsed = JSON.parse(value)
+        (parsed.is_a?(Hash) || parsed.is_a?(Array)) ? parsed : value
+      rescue JSON::ParserError
+        value
+      end
+
+      def truncate(value)
+        return value unless @max_bytes && value.bytesize > @max_bytes
+
+        preview_bytes = [@max_bytes - 64, 1].max
+        preview = value.byteslice(0, preview_bytes).to_s.force_encoding(Encoding::UTF_8).scrub
+        encoded = JSON.generate("truncated" => true, "preview" => preview)
+        while encoded.bytesize > @max_bytes && preview_bytes > 1
+          preview_bytes = [preview_bytes / 2, 1].max
+          preview = value.byteslice(0, preview_bytes).to_s.force_encoding(Encoding::UTF_8).scrub
+          encoded = JSON.generate("truncated" => true, "preview" => preview)
+        end
+        encoded
+      end
+    end
+  end
+end

data/lib/little_ghost/support/executor.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  module Support
+    # Executor runs independent work concurrently while preserving input order in
+    # the final results. It gives framework extensions bounded parallelism without
+    # losing cancellation or request-scoped state.
+    #
+    # ExecutionState is copied to workers. +on_result+ runs on the calling
+    # thread in completion order. After all workers join, the first cleanup
+    # error, or otherwise the first input-order error, is raised.
+    class Executor
+      # Sets the maximum number of worker threads.
+      def initialize(max_concurrency: 8)
+        raise ArgumentError, "max_concurrency must be at least 1" if max_concurrency < 1
+
+        @max_concurrency = max_concurrency
+      end
+
+      # Maps +values+ with at most the configured number of workers.
+      def map(values, cancellation_token: CancellationToken.new, on_result: nil, &block)
+        unless on_result.nil? || on_result.respond_to?(:call)
+          raise ArgumentError, "on_result must be callable"
+        end
+
+        items = values.to_a
+        return [] if items.empty?
+
+        queue = Queue.new
+        completions = Queue.new
+        items.each_index { |index| queue << index }
+        results = Array.new(items.length)
+        errors = Array.new(items.length)
+        worker_count = [@max_concurrency, items.length].min
+        execution_state = ExecutionState.capture
+
+        workers = worker_count.times.map do
+          Thread.new do
+            ExecutionState.with(execution_state) do
+              loop do
+                index = begin
+                  queue.pop(true)
+                rescue ThreadError
+                  break
+                end
+
+                begin
+                  cancellation_token.raise_if_cancelled!
+                  results[index] = block.call(items[index])
+                rescue => error
+                  errors[index] = error
+                ensure
+                  completions << index
+                end
+              end
+            end
+          end
+        end
+        begin
+          items.length.times do
+            index = completions.pop
+            on_result.call(index, results[index]) if on_result && !errors[index]
+          end
+        ensure
+          workers.each(&:join)
+        end
+
+        first_error = errors.compact.find { |error| error.is_a?(CleanupError) } || errors.compact.first
+        raise first_error if first_error
+
+        results
+      end
+    end
+  end
+end

data/lib/little_ghost/support/interruptible_stream.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  module Support
+    # InterruptibleStream turns a blocking producer into a lazy, cancellable Ruby
+    # stream. It is useful when an SDK owns the blocking read but the agent still
+    # needs deadlines and cooperative cancellation.
+    #
+    # The producer receives an emitter callable. Ending enumeration early stops
+    # and joins the producer; CleanupError is raised if it cannot be stopped
+    # within the fixed shutdown bound.
+    #
+    #   stream = LittleGhost::Support::InterruptibleStream.new(
+    #     cancellation_token: token
+    #   ) { |emit| source.each { |value| emit.call(value) } }
+    class InterruptibleStream
+      include Enumerable
+
+      # Raised when the producer thread remains active past the fixed shutdown
+      # bound.
+      class CleanupError < LittleGhost::CleanupError; end
+
+      POLL_INTERVAL = 0.05 # :nodoc:
+      SHUTDOWN_TIMEOUT = 0.1 # :nodoc:
+      BUFFER_SIZE = 16 # :nodoc:
+
+      # Configures a lazy stream. The producer starts when #each is consumed.
+      def initialize(cancellation_token:, deadline: nil, buffer_size: BUFFER_SIZE, &producer)
+        raise ArgumentError, "producer is required" unless producer
+
+        @cancellation_token = cancellation_token
+        @deadline = deadline
+        @buffer_size = Integer(buffer_size)
+        @producer = producer
+        raise ArgumentError, "buffer_size must be positive" unless @buffer_size.positive?
+      end
+
+      # Yields produced values, raising producer, cancellation, deadline, or
+      # cleanup errors in the consuming thread.
+      def each
+        return enum_for(__method__) unless block_given?
+
+        queue = SizedQueue.new(@buffer_size)
+        execution_state = ExecutionState.capture
+        worker = Thread.new do
+          ExecutionState.with(execution_state) do
+            @producer.call(->(value) { queue << [:value, value] })
+          end
+        rescue => error
+          queue << [:error, error]
+        end
+        worker.report_on_exception = false
+
+        loop do
+          check!
+          break if !worker.alive? && queue.empty?
+
+          item = next_item(queue)
+          unless item
+            break if !worker.alive? && queue.empty?
+            next
+          end
+
+          type, value = item
+          check!
+          case type
+          when :value then yield value
+          when :error then raise value
+          end
+        end
+        self
+      ensure
+        if worker
+          worker.kill if worker.alive?
+          worker.join(SHUTDOWN_TIMEOUT)
+          if worker.alive?
+            raise CleanupError,
+              "stream producer did not stop within #{SHUTDOWN_TIMEOUT} seconds"
+          end
+        end
+      end
+
+      private
+
+      def next_item(queue)
+        queue.pop(timeout: wait_timeout)
+      rescue ThreadError
+        nil
+      end
+
+      def wait_timeout
+        return POLL_INTERVAL unless @deadline
+
+        (@deadline - Time.now).clamp(0, POLL_INTERVAL)
+      end
+
+      def check!
+        @cancellation_token.raise_if_cancelled!
+        raise DeadlineExceededError, "The run deadline was reached" if @deadline && Time.now >= @deadline
+      end
+    end
+  end
+end