little_ghost 0.2.1 → 0.4.0

data/lib/little_ghost/data_map.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  # DataMap holds JSON-compatible application data with indifferent key access.
+  # It stores every key as a String while accepting String and Symbol keys for
+  # lookup and mutation, including in nested maps.
+  #
+  #   state = DataMap.new(plan: {status: "active"})
+  #   state.dig("plan", :status) # => "active"
+  #   state.to_h                  # => {"plan" => {"status" => "active"}}
+  #
+  # State and metadata exposed by Sessions and RunContexts use DataMap so they
+  # remain easy to work with in Ruby and portable across session stores. Values
+  # are limited to JSON primitives, Arrays, and mappings. A mapping that
+  # supplies both a String and Symbol form of the same key is ambiguous and
+  # raises ArgumentError.
+  class DataMap < Hash
+    alias_method :store_raw_value, :[]=
+    private :store_raw_value
+
+    # Builds a deeply normalized map from +value+.
+    def initialize(value = {})
+      super()
+      replace(value)
+    end
+
+    # Returns +value+ when it is already a DataMap, or normalizes a mapping.
+    def self.coerce(value)
+      return value if value.is_a?(self)
+
+      new(value)
+    end
+
+    # Looks up +key+ after canonicalizing it to a String.
+    def [](key) = super(normalize_key(key))
+
+    # Stores +value+ under the canonical String form of +key+.
+    def []=(key, value)
+      super(normalize_key(key), normalize_value(value))
+    end
+    alias_method :store, :[]=
+
+    # Fetches +key+ with Hash#fetch's default and block behavior.
+    def fetch(key, *defaults, &block) = super(normalize_key(key), *defaults, &block)
+
+    # Checks for +key+ after canonicalizing it to a String.
+    def key?(key) = super(normalize_key(key))
+    alias_method :has_key?, :key?
+    alias_method :include?, :key?
+    alias_method :member?, :key?
+
+    # Removes +key+ after canonicalizing it to a String.
+    def delete(key, &block) = super(normalize_key(key), &block)
+
+    # Traverses nested DataMaps with String or Symbol keys.
+    def dig(key, *names) = super(normalize_key(key), *names)
+
+    # Returns a normalized copy merged with +other+.
+    def merge(other, &block)
+      dup.merge!(other, &block)
+    end
+
+    # Merges +other+ after deeply normalizing its keys and values.
+    def merge!(other)
+      canonical_pairs(other).each do |key, value|
+        self[key] = (block_given? && key?(key)) ? yield(key, self[key], value) : value
+      end
+      self
+    end
+    alias_method :update, :merge!
+
+    # Replaces all entries with a deeply normalized copy of +other+.
+    def replace(other)
+      pairs = canonical_pairs(other)
+      clear
+      pairs.each { |key, value| self[key] = value }
+      self
+    end
+
+    # Returns a deep independent DataMap copy.
+    def initialize_copy(other)
+      super
+      replace(other.to_h)
+    end
+
+    # Produces a deep ordinary Hash with canonical String keys.
+    def to_h
+      plain_value(self)
+    end
+
+    private
+
+    def canonical_pairs(value, normalize_values: true)
+      hash = Hash.try_convert(value)
+      raise ArgumentError, "DataMap requires a mapping" unless hash
+
+      seen = {}
+      hash.map do |key, child|
+        normalized = normalize_key(key)
+        raise ArgumentError, "DataMap keys must not contain both String and Symbol forms" if seen[normalized]
+
+        seen[normalized] = true
+        [normalized, normalize_values ? normalize_value(child) : child]
+      end
+    end
+
+    def normalize_key(key)
+      return key if key.is_a?(String)
+      return key.to_s if key.is_a?(Symbol)
+
+      raise ArgumentError, "DataMap keys must be Strings or Symbols"
+    end
+
+    def normalize_value(value)
+      return normalize_scalar(value) unless container?(value)
+
+      copy = container_copy(value)
+      stack = [[:visit, value, copy]]
+      ancestors = {}
+      until stack.empty?
+        action, current, target = stack.pop
+        if action == :leave
+          ancestors.delete(current)
+          next
+        end
+
+        raise ArgumentError, "DataMap cannot contain cyclic values" if ancestors[current.object_id]
+
+        ancestors[current.object_id] = true
+        stack << [:leave, current.object_id, nil]
+        if current.is_a?(Hash)
+          canonical_pairs(current, normalize_values: false).reverse_each do |key, child|
+            child_copy = container?(child) ? container_copy(child) : normalize_scalar(child)
+            target.send(:store_raw_value, key, child_copy)
+            stack << [:visit, child, child_copy] if container?(child)
+          end
+        else
+          current.each_with_index do |child, index|
+            child_copy = container?(child) ? container_copy(child) : normalize_scalar(child)
+            target[index] = child_copy
+            stack << [:visit, child, child_copy] if container?(child)
+          end
+        end
+      end
+
+      copy
+    end
+
+    def plain_value(value)
+      return value unless container?(value)
+
+      copy = value.is_a?(Array) ? [] : {}
+      stack = [[:visit, value, copy]]
+      ancestors = {}
+      until stack.empty?
+        action, current, target = stack.pop
+        if action == :leave
+          ancestors.delete(current)
+          next
+        end
+
+        raise ArgumentError, "DataMap cannot contain cyclic values" if ancestors[current.object_id]
+
+        ancestors[current.object_id] = true
+        stack << [:leave, current.object_id, nil]
+        if current.is_a?(Hash)
+          canonical_pairs(current, normalize_values: false).each do |key, child|
+            child_copy = container?(child) ? plain_container_copy(child) : normalize_scalar(child)
+            target[key] = child_copy
+            stack << [:visit, child, child_copy] if container?(child)
+          end
+        else
+          current.each_with_index do |child, index|
+            child_copy = container?(child) ? plain_container_copy(child) : normalize_scalar(child)
+            target[index] = child_copy
+            stack << [:visit, child, child_copy] if container?(child)
+          end
+        end
+      end
+
+      copy
+    end
+
+    def container?(value)
+      value.is_a?(Hash) || value.is_a?(Array)
+    end
+
+    def container_copy(value)
+      value.is_a?(Array) ? [] : self.class.new
+    end
+
+    def plain_container_copy(value)
+      value.is_a?(Array) ? [] : {}
+    end
+
+    def normalize_scalar(value)
+      case value
+      when String, Integer, TrueClass, FalseClass, NilClass
+        value
+      when Float
+        raise ArgumentError, "DataMap values must be JSON-compatible" unless value.finite?
+
+        value
+      else
+        raise ArgumentError, "DataMap values must be JSON-compatible"
+      end
+    end
+  end
+end

data/lib/little_ghost/errors.rb

@@ -13,6 +13,14 @@ module LittleGhost
   class CredentialError < ConfigurationError; end
   # Raised when an invocation payload or operation is invalid.
   class InvocationError < Error; end
+  # Base class for failures coordinating one or more assemblies.
+  class AssemblyError < Error; end
+  # Raised when an assembly exceeds its configured execution bound.
+  class AssemblyLimitError < AssemblyError; end
+  # Raised when an assembly cannot choose one valid next participant.
+  class AssemblyRoutingError < AssemblyError; end
+  # Raised when one assembly step exceeds its local timeout.
+  class AssemblyStepTimeoutError < AssemblyError; end
   # Raised when an invocation contains an unsupported input form.
   class UnsupportedInputError < InvocationError; end
   # Base class for provider response and protocol failures.
@@ -43,8 +51,8 @@ module LittleGhost
   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 an active run cannot accept an interjection.
+  class AgentInterjectionError < InvocationError; end
   # Raised when cancellation stops an operation.
   class CancelledError < Error; end
   # Raised when an operation reaches its deadline.

data/lib/little_ghost/execution.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  # Runs one dormant Run in a supervised worker while the caller remains free to
+  # serve health checks, deliver interjections, or coordinate process shutdown.
+  #
+  #   execution = agent.start_execution(message: "Investigate transfer 481") do |event|
+  #     event_buffer << event
+  #   end
+  #
+  #   execution.interject(message: "Include the latest ledger entry")
+  #   execution.wait(deadline: Time.now + 30)
+  #   execution.run.completed? # => true
+  #
+  # An execution owns its worker. The worker receives a snapshot of the caller's
+  # request-scoped ExecutionState. The Run continues to own its workspace,
+  # sandbox, session, entrypoint, and registered resources. +close+ requests
+  # cooperative cancellation and waits for both the worker and in-flight
+  # interjection calls.
+  class Execution
+    # The supervised Run and an exception raised outside the Run's ordinary
+    # terminal outcome, such as event delivery or cleanup failure.
+    attr_reader :run
+
+    class << self
+      # Starts +run+ immediately and returns its supervising Execution.
+      #
+      # The optional block receives each StreamEvent on the worker thread. It
+      # must be safe to call from that thread and should not retain sensitive
+      # event content longer than the application requires.
+      def start(run, &event_consumer)
+        new(run, event_consumer:).send(:start)
+      end
+    end
+
+    def initialize(run, event_consumer: nil) # :nodoc:
+      raise ArgumentError, "run must be a LittleGhost::Run" unless run.is_a?(Run)
+      unless event_consumer.nil? || event_consumer.respond_to?(:call)
+        raise ArgumentError, "event consumer must be callable"
+      end
+
+      @run = run
+      @event_consumer = event_consumer
+      @state = :pending
+      @error = nil
+      @mutex = Mutex.new
+      @condition = ConditionVariable.new
+      @active_interjections = 0
+      @closing = false
+      @execution_state = ExecutionState.capture
+    end
+
+    # Returns +:pending+, +:running+, or +:finished+.
+    def state
+      @mutex.synchronize { @state }
+    end
+
+    # Returns an event-delivery or cleanup exception raised by the worker.
+    def error
+      @mutex.synchronize { @error }
+    end
+
+    # Indicates that the worker or an interjection call is still active.
+    def active?
+      @mutex.synchronize { @state != :finished || @active_interjections.positive? }
+    end
+
+    # Indicates that the worker and all interjection calls have finished.
+    def finished?
+      !active?
+    end
+
+    # Prepares and delivers one interjection to the active run.
+    #
+    # +payload+ may be a message or a Hash containing +message+ and the options
+    # accepted by Run#interject. Runtime hooks receive the Hash before
+    # delivery, allowing them to materialize trusted application attachments.
+    # Calls may overlap, but +close+ prevents new calls and waits for calls that
+    # have already begun.
+    def interject(payload = nil, **options)
+      if payload.nil? && options.key?(:message)
+        payload = options.delete(:message)
+      end
+      interjection_started = false
+      begin_interjection!
+      interjection_started = true
+      run.interject_with do
+        prepared = run.prepare_interjection(interjection_payload(payload, options))
+        interjection_arguments(prepared, options)
+      end
+    ensure
+      finish_interjection! if interjection_started
+    end
+
+    # Requests cooperative cancellation and returns +self+.
+    def cancel
+      run.cancellation_token.cancel
+      self
+    end
+
+    # Waits for the worker and in-flight interjections, then returns the Run.
+    #
+    # +deadline+ is an absolute Time. Reaching it raises DeadlineExceededError
+    # without cancelling the run. An event-delivery or cleanup failure raised by
+    # the worker is re-raised after all supervised work finishes.
+    def wait(deadline: nil)
+      worker = wait_until_finished(deadline:)
+      worker.join
+      caught = error
+      raise caught if caught
+
+      run
+    end
+
+    # Prevents new interjections, requests cancellation, and waits for shutdown.
+    # The operation is idempotent. +deadline+ has the same meaning as in #wait.
+    def close(deadline: nil)
+      @mutex.synchronize { @closing = true }
+      cancel
+      wait(deadline:)
+    end
+
+    protected
+
+    def start # :nodoc:
+      @mutex.synchronize do
+        raise Error, "execution has already started" unless @state == :pending
+
+        @state = :running
+        @worker = Thread.new { execute }
+      end
+      self
+    end
+
+    private
+
+    def execute
+      ExecutionState.with(@execution_state) do
+        run.each { |event| @event_consumer&.call(event) }
+      end
+    rescue => caught
+      @mutex.synchronize { @error = caught }
+    ensure
+      @mutex.synchronize do
+        @state = :finished
+        @condition.broadcast
+      end
+    end
+
+    def begin_interjection!
+      @mutex.synchronize do
+        raise AgentInterjectionError, "Execution is closing" if @closing
+        raise AgentInterjectionError, "Execution has already finished" if @state == :finished
+
+        @active_interjections += 1
+      end
+    end
+
+    def finish_interjection!
+      @mutex.synchronize do
+        @active_interjections -= 1 if @active_interjections.positive?
+        @condition.broadcast
+      end
+    end
+
+    def interjection_payload(payload, options)
+      values = payload.is_a?(Hash) ? payload.dup : {message: payload}
+      options.each { |key, value| values[key] = value }
+      values
+    end
+
+    def interjection_arguments(prepared, fallback)
+      unless prepared.is_a?(Hash)
+        return [prepared, fallback.slice(:interjection_id, :batch_key, :metadata, :cancellation_token, :deadline)]
+      end
+
+      values = prepared.transform_keys(&:to_sym)
+      message = values.delete(:message) { raise ArgumentError, "prepared interjection must include a message" }
+      allowed = values.slice(:interjection_id, :batch_key, :metadata, :cancellation_token, :deadline)
+      [message, fallback.slice(:interjection_id, :batch_key, :metadata, :cancellation_token, :deadline).merge(allowed)]
+    end
+
+    def wait_until_finished(deadline:)
+      monotonic_deadline = if deadline
+        monotonic_time + [deadline - Time.now, 0].max
+      end
+      @mutex.synchronize do
+        until @state == :finished && @active_interjections.zero?
+          if monotonic_deadline
+            remaining = monotonic_deadline - monotonic_time
+            raise DeadlineExceededError, "Execution did not finish before the wait deadline" unless remaining.positive?
+
+            @condition.wait(@mutex, remaining)
+          else
+            @condition.wait(@mutex)
+          end
+        end
+        @worker
+      end
+    end
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end