little_ghost 0.1.0

data/lib/little_ghost/default_model_registry.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  # Supplies LittleGhost's ready-to-use model selection. The registry maps the
+  # +default+ role to GPT-5.6 Terra on OpenRouter or OpenAI and keeps the selected
+  # provider stable for its runtime.
+  #
+  # Prefixed credentials take precedence over conventional provider variables:
+  #
+  # 1. +LITTLEGHOST_OPENROUTER_API_KEY+
+  # 2. +LITTLEGHOST_OPENAI_API_KEY+
+  # 3. +OPENROUTER_API_KEY+
+  # 4. +OPENAI_API_KEY+
+  #
+  # Blank values are ignored. Resolving the +default+ role requires one supported
+  # key and raises ConfigurationError with the available choices otherwise. The
+  # environment is read when the registry is created, so build a new Runtime
+  # after changing credentials. Configure a ModelRegistry explicitly when the
+  # application needs another provider, model, or logical role.
+  #
+  # *Warning:* Setting any supported key authorizes LittleGhost to send model
+  # inputs, including prompts, conversation history, tool data, and attachments,
+  # to the selected external provider. When more than one key is present, the
+  # precedence above determines that destination. Applications with provider or
+  # data-residency requirements should configure a ModelRegistry explicitly.
+  class DefaultModelRegistry < ModelRegistry
+    CREDENTIALS = [
+      ["LITTLEGHOST_OPENROUTER_API_KEY", :openrouter],
+      ["LITTLEGHOST_OPENAI_API_KEY", :openai],
+      ["OPENROUTER_API_KEY", :openrouter],
+      ["OPENAI_API_KEY", :openai]
+    ].freeze # :nodoc:
+    MODELS = {
+      openrouter: "openai/gpt-5.6-terra",
+      openai: "gpt-5.6-terra"
+    }.freeze # :nodoc:
+    PROVIDERS = {
+      openrouter: Providers::OpenRouter,
+      openai: Providers::OpenAI
+    }.freeze # :nodoc:
+    MISSING_CREDENTIAL_MESSAGE =
+      "No API key is configured for the default model. Set " \
+      "LITTLEGHOST_OPENROUTER_API_KEY, LITTLEGHOST_OPENAI_API_KEY, " \
+      "OPENROUTER_API_KEY, or OPENAI_API_KEY, or configure a custom " \
+      "model registry with LittleGhost.configure." # :nodoc:
+
+    # Selects one provider from the current environment and registers the
+    # +default+ profile. The selection remains fixed for this registry instance.
+    def initialize
+      super
+      variable, provider_name = CREDENTIALS.find { |name, _provider| !ENV[name].to_s.strip.empty? }
+      if variable
+        api_key = ENV.fetch(variable)
+        provider_class = PROVIDERS.fetch(provider_name)
+        provider(provider_name) do |model:, **|
+          provider_class.new(api_key:, model:)
+        end
+        profile("default", provider: provider_name, model: MODELS.fetch(provider_name))
+      else
+        configure_missing_credential
+      end
+    end
+
+    private
+
+    def configure_missing_credential
+      provider(:unconfigured) { |**| raise ConfigurationError, MISSING_CREDENTIAL_MESSAGE }
+      profile("default", provider: :unconfigured, model: MODELS.fetch(:openai))
+    end
+  end
+end

data/lib/little_ghost/errors.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  # Base class for errors raised by LittleGhost.
+  class Error < StandardError; end
+  # Raised for invalid framework or application configuration.
+  class ConfigurationError < Error; end
+  # Raised when an invocation payload or operation is invalid.
+  class InvocationError < Error; end
+  # Raised when an invocation contains an unsupported input form.
+  class UnsupportedInputError < InvocationError; end
+  # Base class for provider response and protocol failures.
+  class ProviderError < Error; end
+  # Raised when a provider violates the expected request-response protocol.
+  class ProtocolError < ProviderError; end
+  # Raised when a provider reports that the request exceeds its context window.
+  class ContextWindowOverflowError < ProviderError; end
+  # Raised when configured generation limits stop the agent before completion.
+  class OutputLimitError < ProtocolError; end
+  # Raised when a model returns an invalid tool-call representation.
+  class MalformedToolCallError < ProtocolError; end
+
+  # Raised when structured output is absent, invalid, or exceeds safety limits.
+  class StructuredResultError < ProtocolError
+    # Declared schema name and validation messages returned by local checking.
+    attr_reader :schema_name, :validation_errors
+
+    # Records the schema and freezes normalized validation messages.
+    def initialize(message, schema_name:, validation_errors: [])
+      @schema_name = schema_name.to_s.freeze
+      @validation_errors = Array(validation_errors).map(&:to_s).freeze
+      super(message)
+    end
+  end
+
+  # Raised when repeated identical tool calls reach the configured termination limit.
+  class ToolLoopError < ProtocolError; end
+  # Base class for failures while executing a tool.
+  class ToolError < Error; end
+  # Raised when an active run cannot accept an interruption.
+  class AgentInterruptError < InvocationError; end
+  # Raised when cancellation stops an operation.
+  class CancelledError < Error; end
+  # Raised when an operation reaches its deadline.
+  class DeadlineExceededError < Error; end
+  # Raised when one or more managed resources fail to close.
+  class CleanupError < Error; end
+end

data/lib/little_ghost/events.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require "json"
+
+module LittleGhost
+  # Events lets an application react to noteworthy agent activity without
+  # coupling LittleGhost to a logger or event backend. Listeners can feed local
+  # diagnostics, alerts, or an application's own event pipeline.
+  #
+  #   class WarningCollector
+  #     attr_reader :events
+  #
+  #     def initialize
+  #       @events = []
+  #     end
+  #
+  #     def emit(event)
+  #       events << event
+  #     end
+  #   end
+  #
+  #   warnings = WarningCollector.new
+  #   LittleGhost::Events.subscribe(warnings) do |event|
+  #     %i[warn error].include?(event[:level])
+  #   end
+  #   LittleGhost::Events.warn("support.case.stalled", case_id: "case-42")
+  #   warnings.events.last[:name] # => "support.case.stalled"
+  #
+  # Events describe point-in-time facts. Instrumentation measures work that has
+  # a start and finish. Payloads are copied, limited to JSON-safe values, and
+  # delivered with context local to the current execution. A broken listener
+  # never breaks the operation that emitted the event.
+  module Events
+    # Severity levels accepted by .emit and its convenience methods.
+    LEVELS = %i[debug info warn error].freeze
+
+    # JSON-lines listener suitable for diagnostics and local development.
+    # Values pass through a Support::Redactor before being written.
+    class ConsoleListener
+      # Writes redacted JSON lines to +io+.
+      def initialize(io: $stderr, redactor: Support::Redactor.new)
+        @io = io
+        @redactor = redactor
+        @mutex = Mutex.new
+      end
+
+      # Emits one complete JSON line atomically.
+      def emit(event)
+        @mutex.synchronize { @io.puts(JSON.generate(@redactor.call(event))) }
+      end
+    end
+
+    # Thread-safe event publisher with process-wide and fiber-scoped listeners.
+    # Reporters start without listeners so applications opt into their preferred
+    # event destination, including +ConsoleListener+ for JSON-line diagnostics.
+    class Reporter
+      # Starts with +listeners+ in subscription order.
+      def initialize(listeners: [])
+        @mutex = Mutex.new
+        @listeners = []
+        Array(listeners).each { |listener| subscribe(listener) }
+      end
+
+      # Subscribes +listener+. The optional block filters copied event hashes.
+      def subscribe(listener, &filter)
+        unless listener.respond_to?(:emit)
+          raise ArgumentError, "event listener must respond to emit"
+        end
+
+        @mutex.synchronize { @listeners << {listener:, filter:} }
+        listener
+      end
+
+      # Unsubscribes every entry matching +listener+.
+      def unsubscribe(listener)
+        @mutex.synchronize do
+          @listeners.delete_if { |entry| listener === entry.fetch(:listener) }
+        end
+        listener
+      end
+
+      # Delivers an event and returns a detached copy of its complete hash.
+      def emit(level, name, payload = {})
+        level = level.to_sym
+        raise ArgumentError, "unknown event level: #{level}" unless LEVELS.include?(level)
+        raise ArgumentError, "event payload must be a hash" unless payload.is_a?(Hash)
+
+        event = {
+          name: normalize_string(name.to_s),
+          level:,
+          payload: deep_copy(payload),
+          context: context,
+          timestamp: Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond)
+        }
+        listeners.each do |entry|
+          listener = entry.fetch(:listener)
+          filter = entry[:filter]
+          next if filter && !filter.call(deep_copy(event))
+
+          listener.emit(deep_copy(event))
+        rescue
+          nil
+        end
+        event
+      end
+
+      # Adds attributes to events emitted while the block runs.
+      def with_context(attributes)
+        values = context.merge(deep_copy(attributes.compact))
+        ExecutionState.with(context_key => values) { yield }
+      end
+
+      # Copies the event context active in the current execution.
+      def context
+        deep_copy(ExecutionState[context_key] || {})
+      end
+
+      private
+
+      def listeners
+        scoped = ExecutionState[:little_ghost_event_listeners] || []
+        @mutex.synchronize { @listeners.dup } + scoped
+      end
+
+      def context_key = :little_ghost_event_context
+
+      def deep_copy(value, ancestors = {}, depth = 0)
+        raise ArgumentError, "event payload is nested too deeply" if depth > 100
+
+        case value
+        when Hash
+          copy_container(value, ancestors) do
+            value.to_h do |key, item|
+              unless key.is_a?(String) || key.is_a?(Symbol)
+                raise ArgumentError, "event payload keys must be strings or symbols"
+              end
+
+              [copy_key(key), deep_copy(item, ancestors, depth + 1)]
+            end
+          end
+        when Array
+          copy_container(value, ancestors) do
+            value.map { |item| deep_copy(item, ancestors, depth + 1) }
+          end
+        when String
+          normalize_string(value)
+        when Float
+          raise ArgumentError, "event payload numbers must be finite" unless value.finite?
+
+          value
+        when Symbol
+          copy_symbol(value)
+        when Integer, true, false, nil
+          value
+        else
+          raise ArgumentError, "event payload values must be JSON-safe"
+        end
+      end
+
+      def copy_container(value, ancestors)
+        identity = value.object_id
+        raise ArgumentError, "event payload must not contain cycles" if ancestors.key?(identity)
+
+        ancestors[identity] = true
+        yield
+      ensure
+        ancestors.delete(identity) if identity
+      end
+
+      def copy_key(key)
+        return copy_symbol(key) if key.is_a?(Symbol)
+
+        normalize_string(key.to_s)
+      end
+
+      def copy_symbol(value)
+        text = value.to_s
+        return value if text.ascii_only? || (text.encoding == Encoding::UTF_8 && text.valid_encoding?)
+
+        normalize_string(text)
+      end
+
+      def normalize_string(value)
+        value.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "\uFFFD")
+      end
+    end
+
+    class << self
+      # Accesses the process-wide reporter.
+      def reporter
+        reporter_mutex.synchronize { @reporter ||= Reporter.new }
+      end
+
+      # Replaces the process-wide reporter. Existing references are unaffected.
+      def reporter=(value)
+        raise ArgumentError, "reporter must be an event reporter" unless value.is_a?(Reporter)
+
+        reporter_mutex.synchronize do
+          @reporter&.unsubscribe(@console_listener) if @console_listener
+          @reporter = value
+          @reporter.subscribe(@console_listener) if @console_listener
+        end
+      end
+
+      # The process-wide JSON-line console destination, or +nil+ when console
+      # delivery is disabled.
+      def console_output
+        reporter_mutex.synchronize { @console_output }
+      end
+
+      # Selects +:stdout+, +:stderr+, or +nil+ as the process-wide JSON-line
+      # console destination. Replacing the destination leaves other listeners
+      # unchanged.
+      def console_output=(destination)
+        unless [nil, :stdout, :stderr].include?(destination)
+          raise ArgumentError, "event log destination must be :stdout, :stderr, or nil"
+        end
+
+        reporter_mutex.synchronize do
+          @reporter ||= Reporter.new
+          @reporter.unsubscribe(@console_listener) if @console_listener
+          @console_output = destination
+          @console_listener = destination && ConsoleListener.new(io: (destination == :stdout) ? $stdout : $stderr)
+          @reporter.subscribe(@console_listener) if @console_listener
+        end
+      end
+
+      # Subscribes a process-wide listener.
+      def subscribe(...) = reporter.subscribe(...)
+      # Unsubscribes a process-wide listener.
+      def unsubscribe(...) = reporter.unsubscribe(...)
+      # Adds event context while a block runs.
+      def with_context(...) = reporter.with_context(...)
+      # Copies the current event context.
+      def context = reporter.context
+
+      LEVELS.each do |level|
+        define_method(level) do |name, payload = nil, **attributes|
+          if payload && !payload.is_a?(Hash)
+            raise ArgumentError, "event payload must be a hash"
+          end
+
+          values = payload ? payload.merge(attributes) : attributes
+          reporter.emit(level, name, values)
+        end
+      end
+
+      # Subscribes +listener+ only while the block runs.
+      def subscribed(listener, &block)
+        raise ArgumentError, "event listener must respond to emit" unless listener.respond_to?(:emit)
+
+        listeners = ExecutionState[:little_ghost_event_listeners] || []
+        entry = {listener:, filter: nil}
+        ExecutionState.with(little_ghost_event_listeners: listeners + [entry], &block)
+      end
+
+      private
+
+      def reporter_mutex
+        @reporter_mutex ||= Mutex.new
+      end
+    end
+  end
+end

data/lib/little_ghost/execution_state.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  # ExecutionState carries request-scoped values across fibers and the worker
+  # threads LittleGhost creates. It keeps event and instrumentation context from
+  # leaking between concurrent runs.
+  #
+  # Framework extensions may use #capture and #with to preserve event and
+  # instrumentation context. Captured hashes are immutable; values within them
+  # are not deep-copied.
+  module ExecutionState
+    STORAGE_KEY = :little_ghost_execution_state # :nodoc:
+    EMPTY_STATE = {}.freeze # :nodoc:
+
+    class << self
+      # Reads +key+ from the current execution state.
+      def [](key)
+        state[key]
+      end
+
+      # Replaces +key+ in the current fiber-local state.
+      def []=(key, value)
+        replace(state.merge(key => value))
+      end
+
+      # Deletes +key+ and returns its previous value.
+      def delete(key)
+        value = state[key]
+        replace(state.except(key))
+        value
+      end
+
+      # Captures the current immutable state hash for propagation.
+      def capture
+        state
+      end
+
+      # Merges +values+ while the block runs, then restores prior state.
+      def with(values)
+        previous = state
+        replace(previous.merge(values))
+        yield
+      ensure
+        replace(previous)
+      end
+
+      private
+
+      def state
+        Fiber[STORAGE_KEY] || EMPTY_STATE
+      end
+
+      def replace(values)
+        Fiber[STORAGE_KEY] = values.empty? ? nil : values.freeze
+      end
+    end
+  end
+end