little_ghost 0.1.0

data/lib/little_ghost/configuration.rb

@@ -0,0 +1,337 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module LittleGhost
+  # Configure shared services and lookup rules before agents start.
+  # A configuration collects model profiles, persistence, paths,
+  # instrumentation, and runtime hooks for an application.
+  #
+  #   LittleGhost.configure do |config|
+  #     config.models CustomerSupportModels
+  #     config.default_model :customer_support
+  #     config.service_name "support-api"
+  #   end
+  #
+  #   LittleGhost.configuration.default_model # => "customer_support"
+  #   LittleGhost.configuration.service_name  # => "support-api"
+  #
+  # Prompt and skill lookup paths default to +app/prompts+ and +app/skills+
+  # under the application root. Applications may append shared roots or replace
+  # the arrays entirely.
+  #
+  # Configuration is a mutable builder, while each Runtime owns a settings
+  # snapshot. The first runtime for a root loads +config/little_ghost.rb+ once;
+  # later mutations do not alter that runtime, and one configuration cannot load
+  # files for two different roots.
+  #
+  # Session actor resolvers belong at an authentication boundary. Multi-tenant
+  # applications should derive actor identity from trusted authenticated state,
+  # not from an unverified request field.
+  class Configuration
+    FILE_LOAD_MUTEX = Mutex.new # :nodoc:
+    CONFIGURATION_KEYS = %i[invocation models default_model service_name].freeze # :nodoc:
+    DEFAULT_PROMPT_PATHS = ["app/prompts"].freeze # :nodoc:
+    DEFAULT_SKILL_PATHS = ["app/skills"].freeze # :nodoc:
+
+    ##
+    # The request envelope class used to parse application payloads.
+    #
+    # :method: invocation
+    # :call-seq:
+    #   invocation() -> value
+    #   invocation(value) -> value
+
+    ##
+    # The model registry class or instance used to resolve logical roles. By
+    # default, +DefaultModelRegistry+ selects a built-in provider from supported
+    # environment variables.
+    #
+    # :method: models
+    # :call-seq:
+    #   models() -> value
+    #   models(value) -> value
+
+    ##
+    # The fallback logical model role for agents without an explicit role.
+    # Values are normalized to strings.
+    #
+    # :method: default_model
+    # :call-seq:
+    #   default_model() -> String, nil
+    #   default_model(value) -> String
+
+    ##
+    # The low-cardinality service name attached to instrumentation.
+    #
+    # :method: service_name
+    # :call-seq:
+    #   service_name() -> value
+    #   service_name(value) -> value
+    CONFIGURATION_KEYS.each do |name|
+      define_method(name) do |value = :__read__|
+        return configuration_values[name] if value == :__read__
+
+        configuration_values[name] = (name == :default_model) ? value.to_s : value
+      end
+    end
+
+    ##
+    # Replaces the request envelope class for subsequently built runtimes.
+    # :method: invocation=
+    # :call-seq:
+    #   invocation=(value) -> value
+
+    ##
+    # Replaces the model registry declaration for subsequently built runtimes.
+    # :method: models=
+    # :call-seq:
+    #   models=(value) -> value
+
+    ##
+    # Replaces the fallback logical model role and normalizes it to a String.
+    # :method: default_model=
+    # :call-seq:
+    #   default_model=(value) -> String
+
+    ##
+    # Replaces the service name attached to telemetry from new runtimes.
+    # :method: service_name=
+    # :call-seq:
+    #   service_name=(value) -> value
+    CONFIGURATION_KEYS.each do |name|
+      define_method("#{name}=") { |value| public_send(name, value) }
+    end
+
+    # Starts a mutable builder with optional +values+.
+    #
+    # Prompt paths default to +app/prompts+ and skill paths to +app/skills+.
+    # Collection settings are copied so callers can safely reuse their input
+    # arrays after construction.
+    def initialize(values = {})
+      @configuration_values = {
+        prompt_paths: DEFAULT_PROMPT_PATHS.dup,
+        skill_paths: DEFAULT_SKILL_PATHS.dup,
+        skill_resource_root: nil,
+        workspace: nil,
+        sandbox: nil,
+        instrumentation_subscribers: [],
+        runtime_hooks: []
+      }.merge(values)
+      @configuration_values[:prompt_paths] = Array(@configuration_values[:prompt_paths]).dup
+      @configuration_values[:skill_paths] = Array(@configuration_values[:skill_paths]).dup
+      @configuration_values[:instrumentation_subscribers] = Array(
+        @configuration_values[:instrumentation_subscribers]
+      ).dup
+      @configuration_values[:runtime_hooks] = Array(@configuration_values[:runtime_hooks]).dup
+    end
+
+    # Yields this builder for setup and returns the same instance.
+    def configure
+      yield self if block_given?
+      self
+    end
+
+    # Workspace declaration used for subsequently built runtimes.
+    def workspace = configuration_values[:workspace]
+    # Sandbox declaration used for subsequently built runtimes.
+    def sandbox = configuration_values[:sandbox]
+    # Session-store declaration used for subsequently built runtimes.
+    def session_store = configuration_values[:session_store]
+
+    # Selects the Workspace subclass instantiated for each run.
+    def workspace=(value)
+      @configuration_values[:workspace] = component_class(value, Workspace, :workspace)
+    end
+
+    # Selects the Sandbox subclass instantiated around each run's workspace.
+    def sandbox=(value)
+      @configuration_values[:sandbox] = component_class(value, Sandbox, :sandbox)
+    end
+
+    # Selects session persistence with a +:provider+ and its constructor options.
+    #
+    # The provider must be a SessionStore subclass. Runtime construction creates
+    # and owns the store instance.
+    def session_store=(value)
+      unless value.is_a?(Hash)
+        raise ArgumentError, "session_store must be a hash with a provider"
+      end
+
+      provider = value[:provider]
+      @configuration_values[:session_store] = value.merge(provider: component_class(provider, SessionStore, :session_store))
+    end
+
+    # Looks up an arbitrary setting by symbol or string-compatible name.
+    def [](name)
+      configuration_values.fetch(name.to_sym)
+    end
+
+    # Adds or replaces an arbitrary setting.
+    def []=(name, value)
+      configuration_values[name.to_sym] = value
+    end
+
+    # Replaces the application root after resolving it to a stable real path.
+    def root=(value)
+      root(value)
+    end
+
+    # Adds an Instrumentation::Subscriber to each new runtime and returns it.
+    def instrument(subscriber)
+      unless subscriber.is_a?(Instrumentation::Subscriber)
+        raise ArgumentError, "instrumentation subscriber must be a LittleGhost::Instrumentation::Subscriber"
+      end
+
+      configuration_values[:instrumentation_subscribers] << subscriber
+      subscriber
+    end
+
+    # :call-seq:
+    #   log_events_to() -> :stdout, :stderr, nil
+    #   log_events_to(destination) -> destination
+    #
+    # Sends structured framework events to +:stdout+ or +:stderr+. This setting
+    # controls the process-wide Events console destination; the most recent
+    # setting replaces it without changing other event listeners. By default,
+    # events have no console destination. Passing +nil+ disables console output.
+    # The console listener redacts sensitive values and writes one JSON object
+    # per line.
+    def log_events_to(destination = :__read__)
+      return Events.console_output if destination == :__read__
+
+      Events.console_output = destination
+    end
+
+    # Replaces the console destination for structured framework events.
+    def log_events_to=(destination)
+      log_events_to(destination)
+    end
+
+    # Adds a Runtime::Hook subclass to each new runtime and returns it.
+    def runtime_hook(hook_class)
+      unless hook_class.is_a?(Class) && hook_class <= Runtime::Hook
+        raise ArgumentError, "runtime_hook must be a LittleGhost::Runtime::Hook class"
+      end
+
+      configuration_values[:runtime_hooks] << hook_class
+      hook_class
+    end
+
+    # :call-seq:
+    #   session_actor() -> callable, nil
+    #   session_actor(callable) -> callable
+    #   session_actor { |invocation| ... } -> callable
+    #
+    # The callable that derives the persistence actor for each invocation.
+    #
+    # Pass either a callable or a block. The configured resolver should use
+    # trusted authenticated identity in multi-tenant applications.
+    def session_actor(value = :__read__, &resolver)
+      return configuration_values[:session_actor] if value == :__read__ && !resolver
+
+      raise ArgumentError, "Provide a session actor resolver or a block, not both" if value != :__read__ && resolver
+
+      configured = resolver || value
+      raise ArgumentError, "session_actor must be callable" unless configured.respond_to?(:call)
+
+      configuration_values[:session_actor] = configured
+    end
+
+    # :call-seq:
+    #   root() -> Pathname
+    #   root(path) -> Pathname
+    #
+    # The resolved application root, defaulting to +Dir.pwd+.
+    #
+    # Setting or reading an invalid root raises ConfigurationError. Symlinks are
+    # resolved so runtimes and lookup paths share one stable boundary.
+    def root(value = :__read__)
+      if value != :__read__
+        return configuration_values[:root] = canonical_root(value)
+      end
+
+      configured = configuration_values[:root]
+      configured ? canonical_root(configured) : inferred_root
+    end
+
+    # Mutable prompt lookup paths, in precedence order.
+    def prompt_paths = configuration_values[:prompt_paths]
+
+    # Replaces prompt lookup paths with +value+ converted to an Array.
+    def prompt_paths=(value)
+      configuration_values[:prompt_paths] = Array(value)
+    end
+
+    # Mutable skill lookup paths, in precedence order.
+    def skill_paths = configuration_values[:skill_paths]
+
+    # Replaces skill lookup paths with +value+ converted to an Array.
+    def skill_paths=(value)
+      configuration_values[:skill_paths] = Array(value)
+    end
+
+    # Optional trusted root exposed to skills for resource lookup.
+    def skill_resource_root = configuration_values[:skill_resource_root]
+
+    # Replaces the trusted skill resource root for new runtimes.
+    def skill_resource_root=(value)
+      configuration_values[:skill_resource_root] = value
+    end
+
+    def settings(root: nil) # :nodoc:
+      requested_root = root && canonical_root(root)
+      values = configuration_values.dup
+      values[:prompt_paths] = Array(values[:prompt_paths]).dup
+      values[:skill_paths] = Array(values[:skill_paths]).dup
+      values[:instrumentation_subscribers] = Array(values[:instrumentation_subscribers]).dup
+      values[:runtime_hooks] = Array(values[:runtime_hooks]).dup
+      values[:root] = requested_root || values[:root] || self.root
+      values
+    end
+
+    def load_file!(root: nil) # :nodoc:
+      requested_root = canonical_root(root || self.root)
+      FILE_LOAD_MUTEX.synchronize do
+        (@configuration_file_mutex ||= Mutex.new).synchronize do
+          if @configuration_file_root
+            return self if @configuration_file_root == requested_root
+
+            raise ConfigurationError, "configuration file is already loaded for #{@configuration_file_root}"
+          end
+
+          path = File.join(requested_root, "config/little_ghost.rb")
+          LittleGhost.with_configuration(self) { Kernel.load(path) } if File.file?(path)
+          @configuration_file_root = requested_root
+        end
+      end
+
+      self
+    end
+
+    private
+
+    attr_reader :configuration_values
+
+    def component_class(value, base_class, name)
+      unless value.is_a?(Class) && value <= base_class
+        raise ArgumentError, "#{name} must be a #{base_class} class"
+      end
+
+      value
+    end
+
+    def inferred_root
+      canonical_root(Dir.pwd)
+    end
+
+    def canonical_root(value)
+      path = Pathname.new(File.realpath(File.expand_path(value)))
+      raise ConfigurationError, "application root must be a directory" unless path.directory?
+
+      path
+    rescue Errno::ENOENT
+      raise ConfigurationError, "application root must exist"
+    end
+  end
+end

data/lib/little_ghost/content.rb

@@ -0,0 +1,324 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+
+module LittleGhost
+  # Content gives messages a shared vocabulary for text, attachments, tool calls,
+  # tool results, and model reasoning. The same blocks move between agents,
+  # providers, tools, and sessions without leaking a provider's wire format.
+  #
+  #   block = LittleGhost::Content::Text.new(text: "Hello")
+  #   LittleGhost::Content.normalize("Hello") == block # => true
+  #
+  # Every block serializes through
+  # {Content.serialize}[rdoc-ref:LittleGhost::Content.serialize]. Binary data uses
+  # strict base64 encoding in the serialized form.
+  module Content
+    Serializable = Module.new do # :nodoc:
+      def to_h = Content.serialize(self)
+      def to_json(*arguments) = JSON.generate(to_h, *arguments)
+    end
+
+    # Contains model-visible text.
+    Text = Data.define(:text) { include Serializable } # :nodoc:
+    # Contains binary image +data+ and its MIME +media_type+.
+    Image = Data.define(:data, :media_type) { include Serializable } # :nodoc:
+    # Contains binary document +data+, MIME +media_type+, and display +name+.
+    Document = Data.define(:data, :media_type, :name) { include Serializable } # :nodoc:
+    # Describes a provider-requested tool call.
+    ToolUse = Data.define(:id, :name, :input) do # :nodoc:
+      include Serializable
+
+      def initialize(id:, name:, input:)
+        id = String(id)
+        name = String(name)
+        raise ArgumentError, "tool use id is required" if id.empty?
+        raise ArgumentError, "tool use name is required" if name.empty?
+        raise ArgumentError, "tool use input must be an object" unless input.is_a?(Hash)
+
+        super(id: id.to_s, name: name.to_s, input:)
+      rescue TypeError
+        raise ArgumentError, "tool use id and name must be strings"
+      end
+    end
+    # Contains the result for one ToolUse. +status+ is +:success+ or +:error+.
+    ToolResult = Data.define(:tool_use_id, :content, :status) do # :nodoc:
+      include Serializable
+
+      def initialize(tool_use_id:, content:, status:)
+        tool_use_id = String(tool_use_id)
+        status = status.to_sym
+        raise ArgumentError, "tool result id is required" if tool_use_id.empty?
+        raise ArgumentError, "tool result status must be success or error" unless %i[success error].include?(status)
+
+        super(tool_use_id: tool_use_id.freeze, content:, status:)
+      rescue TypeError, NoMethodError
+        raise ArgumentError, "tool result id and status are invalid"
+      end
+    end
+    # Contains provider reasoning text, a provider signature, encrypted redacted
+    # bytes, or provider-specific detail objects.
+    #
+    # Redacted bytes are mutually exclusive with text and signatures so they can
+    # round-trip without exposing or changing provider-managed content.
+    Reasoning = Data.define(:text, :signature, :redacted_content, :details) do # :nodoc:
+      include Serializable
+
+      def initialize(text: "", signature: nil, redacted_content: nil, details: nil)
+        text = String(text)
+        signature = String(signature) if signature
+        redacted_content = String(redacted_content).b if redacted_content
+        if details
+          unless details.is_a?(Array) && details.all? { |detail| detail.is_a?(Hash) }
+            raise ArgumentError, "reasoning details must be an array of objects"
+          end
+        end
+        if redacted_content && (!text.empty? || !signature.to_s.empty?)
+          raise ArgumentError, "reasoning content cannot contain both text and redacted content"
+        end
+
+        super(
+          text: text.freeze,
+          signature: signature&.freeze,
+          redacted_content: redacted_content&.freeze,
+          details:
+        )
+      rescue TypeError
+        raise ArgumentError, "reasoning content is invalid"
+      end
+    end
+
+    # Contains model-visible text.
+    class Text < Data # :doc:
+      ##
+      # :singleton-method: new
+      # :call-seq:
+      #   new(text:) -> Text
+      #
+      # Wraps +text+ without copying it.
+
+      ##
+      # :attr_reader: text
+      # The text shown to the model or application.
+    end
+
+    # Contains binary image data and its MIME media type. Content.serialize
+    # base64-encodes +data+ when the block crosses a JSON boundary.
+    class Image < Data # :doc:
+      ##
+      # :singleton-method: new
+      # :call-seq:
+      #   new(data:, media_type:) -> Image
+      #
+      # Wraps the supplied values without copying them.
+
+      ##
+      # :attr_reader: data
+      # The original binary image bytes.
+
+      ##
+      # :attr_reader: media_type
+      # The image MIME type, such as +image/png+.
+    end
+
+    # Contains binary document data, its MIME media type, and a display name.
+    # Content.serialize base64-encodes +data+ when the block crosses a JSON
+    # boundary.
+    class Document < Data # :doc:
+      ##
+      # :singleton-method: new
+      # :call-seq:
+      #   new(data:, media_type:, name:) -> Document
+      #
+      # Wraps the supplied values without copying them.
+
+      ##
+      # :attr_reader: data
+      # The original binary document bytes.
+
+      ##
+      # :attr_reader: media_type
+      # The document MIME type, such as +application/pdf+.
+
+      ##
+      # :attr_reader: name
+      # The filename or label presented to the model.
+    end
+
+    # Describes one tool call requested by a provider-backed model.
+    class ToolUse < Data # :doc:
+      ##
+      # :singleton-method: new
+      # :call-seq:
+      #   new(id:, name:, input:) -> ToolUse
+      #
+      # Requires non-empty String-compatible +id+ and +name+ values and an
+      # object-shaped +input+.
+
+      ##
+      # :attr_reader: id
+      # The non-empty provider call identifier used to match a ToolResult.
+
+      ##
+      # :attr_reader: name
+      # The non-empty model-visible tool name.
+
+      ##
+      # :attr_reader: input
+      # The object-shaped arguments supplied by the model.
+    end
+
+    # Carries the model-facing result for one ToolUse. A successful result uses
+    # +:success+; a caller-safe failure uses +:error+.
+    class ToolResult < Data # :doc:
+      ##
+      # :singleton-method: new
+      # :call-seq:
+      #   new(tool_use_id:, content:, status:) -> ToolResult
+      #
+      # Requires a non-empty String-compatible +tool_use_id+ and a +status+ of
+      # +:success+ or +:error+.
+
+      ##
+      # :attr_reader: tool_use_id
+      # The ToolUse identifier this result answers.
+
+      ##
+      # :attr_reader: content
+      # The content returned to the model.
+
+      ##
+      # :attr_reader: status
+      # Either +:success+ or +:error+.
+    end
+
+    # Preserves provider reasoning without forcing every provider into one
+    # representation. A value may carry visible text, a provider signature,
+    # opaque redacted bytes, or provider-specific detail objects.
+    #
+    # Redacted bytes are mutually exclusive with text and signatures so they can
+    # round-trip without exposing or changing provider-managed content.
+    class Reasoning < Data # :doc:
+      ##
+      # :singleton-method: new
+      # :call-seq:
+      #   new(text: "", signature: nil, redacted_content: nil, details: nil) -> Reasoning
+      #
+      # +details+, when present, must be an array of Hash objects.
+
+      ##
+      # :attr_reader: text
+      # Visible reasoning text, or an empty string when none is available.
+
+      ##
+      # :attr_reader: signature
+      # An optional provider signature associated with +text+.
+
+      ##
+      # :attr_reader: redacted_content
+      # Optional opaque bytes that only the provider should interpret.
+
+      ##
+      # :attr_reader: details
+      # Optional provider-specific reasoning objects.
+    end
+
+    module_function
+
+    # Accepts an existing block, a String, or a serialized Hash.
+    def normalize(value)
+      case value
+      when Text, Image, Document, ToolUse, ToolResult, Reasoning
+        value
+      when String
+        Text.new(text: value)
+      when Hash
+        from_hash(value)
+      else
+        raise ArgumentError, "Unsupported content block: #{value.class}"
+      end
+    end
+
+    # Reconstructs a content block from its serialized hash.
+    def from_hash(value)
+      hash = value.transform_keys(&:to_sym)
+      type = hash.delete(:type)&.to_sym
+      encoding = hash.delete(:encoding)
+      if encoding.to_s == "base64"
+        encoded = hash.delete(:data)
+        raise ArgumentError, "base64 data is required" unless encoded.is_a?(String)
+
+        decoded = Base64.strict_decode64(encoded)
+        if type == :reasoning
+          hash[:redacted_content] = decoded
+        else
+          hash[:data] = decoded
+        end
+      end
+      if type == :tool_result
+        hash[:status] = hash[:status].to_sym if hash[:status]
+        if hash[:content].is_a?(Array)
+          hash[:content] = hash[:content].map do |block|
+            if block.is_a?(Hash) && (block.key?(:type) || block.key?("type"))
+              normalize(block)
+            else
+              block
+            end
+          end
+        end
+      end
+      klass = {
+        text: Text,
+        image: Image,
+        document: Document,
+        tool_use: ToolUse,
+        tool_result: ToolResult,
+        reasoning: Reasoning
+      }.fetch(type) { raise ArgumentError, "Unsupported content type: #{type.inspect}" }
+      klass.new(**hash)
+    rescue ArgumentError, KeyError => error
+      raise ArgumentError, "Invalid #{type || "content"} block: #{error.message}"
+    end
+
+    # Produces the JSON-safe representation of +block+.
+    def serialize(block)
+      case block
+      when Text then {"type" => "text", "text" => block.text}
+      when Reasoning
+        {"type" => "reasoning", "text" => block.text}.tap do |value|
+          value["signature"] = block.signature if block.signature
+          if block.redacted_content
+            value["data"] = Base64.strict_encode64(block.redacted_content)
+            value["encoding"] = "base64"
+          end
+          value["details"] = block.details if block.details
+        end
+      when Image
+        binary("image", block.data, media_type: block.media_type)
+      when Document
+        binary("document", block.data, media_type: block.media_type, name: block.name)
+      when ToolUse
+        {"type" => "tool_use", "id" => block.id, "name" => block.name, "input" => block.input}
+      when ToolResult
+        {
+          "type" => "tool_result", "tool_use_id" => block.tool_use_id,
+          "content" => serialize_tool_result_content(block.content), "status" => block.status.to_s
+        }
+      else
+        raise ArgumentError, "Unsupported content block: #{block.class}"
+      end
+    end
+
+    def binary(type, data, **attributes) # :nodoc:
+      {"type" => type, "data" => Base64.strict_encode64(data), "encoding" => "base64"}
+        .merge(attributes.transform_keys(&:to_s))
+    end
+
+    def serialize_tool_result_content(content) # :nodoc:
+      return content unless content.is_a?(Array)
+
+      content.map { |block| block.respond_to?(:to_h) ? block.to_h : block }
+    end
+  end
+end