little_ghost 0.5.0 → 0.7.0

data/lib/little_ghost/code_mode/ruby/host.rb

@@ -6,6 +6,9 @@ module LittleGhost
       module Host # :nodoc:
         SOURCE = <<~'RUBY'
             require "json"
+            protocol_output = STDOUT.dup
+            protocol_output.sync = true
+            STDOUT.reopen(STDERR)
             STDOUT.sync = true
             begin
             read_exactly = lambda do |length|
@@ -21,9 +24,9 @@ module LittleGhost
             write_frame = lambda do |value|
               payload = JSON.generate(value)
               raise "protocol frame too large" if payload.bytesize > 64 * 1024 * 1024
-              STDOUT.write([payload.bytesize].pack("N"))
-              STDOUT.write(payload)
-              STDOUT.flush
+              protocol_output.write([payload.bytesize].pack("N"))
+              protocol_output.write(payload)
+              protocol_output.flush
             end
             request = read_frame.call
             catalog = request.fetch("catalog")
@@ -32,7 +35,40 @@ module LittleGhost
             response_queues = {}
             calls = 0
             max_calls = request.fetch("tool_calls")
-            emit = ->(value) { write_lock.synchronize { write_frame.call(value) } }
+            output_buffer = +""
+            flush_output = lambda do
+              unless output_buffer.empty?
+                value = output_buffer.dup
+                output_buffer.clear
+                write_frame.call(type: "text", value: value)
+              end
+            end
+            emit = lambda do |value|
+              write_lock.synchronize do
+                flush_output.call
+                write_frame.call(value)
+              end
+            end
+            program_output = Object.new
+            program_output.define_singleton_method(:write) do |value|
+              value = String(value)
+              write_lock.synchronize do
+                output_buffer << value
+                flush_output.call if output_buffer.bytesize >= 16_384 || value.include?("\n")
+              end
+              value.bytesize
+            end
+            program_output.define_singleton_method(:flush) do
+              write_lock.synchronize { flush_output.call }
+              self
+            end
+            program_output.define_singleton_method(:sync) { false }
+            program_output.define_singleton_method(:sync=) do |value|
+              flush if value
+              value
+            end
+            program_output.define_singleton_method(:tty?) { false }
+            $stdout = program_output
             reader = Thread.new do
               loop do
                 response = read_frame.call
@@ -51,9 +87,7 @@ module LittleGhost
                 response_queues[id] = queue
                 [id, queue]
               end
-              write_lock.synchronize do
-                write_frame.call(type: "call", id: id, name: name, arguments: arguments)
-              end
+              emit.call(type: "call", id: id, name: name, arguments: arguments)
               response = queue.pop
               queues_lock.synchronize { response_queues.delete(id) }
               raise response.fetch("error") if response["error"]
@@ -75,7 +109,12 @@ module LittleGhost
             end
             Object.const_set(:ALL_TOOLS, catalog.freeze) unless Object.const_defined?(:ALL_TOOLS)
             Object.const_set(:FRAME, request["frame"].freeze) if request["frame"] && !Object.const_defined?(:FRAME)
-            context = Object.new
+            evaluation_context = Class.new do
+              def evaluate(source)
+                instance_eval(source, "(code-mode)", 1)
+              end
+            end
+            context = evaluation_context.new
             finished = false
             finish_value = nil
             context.define_singleton_method(:tools) { tools }
@@ -85,14 +124,15 @@ module LittleGhost
               finish_value = value
               throw :little_ghost_finish
             end
-            value = catch(:little_ghost_finish) { context.instance_eval(request.fetch("source"), "(code-mode)", 1) }
+            value = catch(:little_ghost_finish) { context.evaluate(request.fetch("source")) }
             value = finish_value if finished
             emit.call(type: "done", value: value)
           rescue SignalException
             exit 0
           rescue Exception => error
             STDERR.puts("#{error.class}: #{error.message}")
-            write_frame&.call(type: "error", error: "#{error.class}: #{error.message}")
+            error_frame = {type: "error", error: "#{error.class}: #{error.message}"}
+            emit ? emit.call(error_frame) : write_frame&.call(error_frame)
             exit 1
             end
         RUBY

data/lib/little_ghost/code_mode/ruby/session.rb

@@ -14,6 +14,7 @@ module LittleGhost
 
         def initialize(broker:, sandbox_factory:, subprocess_policy:, limits:, observation_seconds: OBSERVATION_SECONDS)
           @broker = broker
+          @task_runner = broker.task_runner
           @sandbox_factory = sandbox_factory
           @subprocess_policy = subprocess_policy
           @limits = limits
@@ -28,8 +29,9 @@ module LittleGhost
           @control_mutex = Mutex.new
           @programs = 0
           @call_mutex = Mutex.new
-          @call_threads = []
+          @call_tasks = []
           @call_errors = []
+          @tool_calls = 0
           @closing_marker = {closing: false}
           @lifecycle_mutex = Mutex.new
           @lifecycle_condition = ConditionVariable.new
@@ -190,6 +192,7 @@ module LittleGhost
           @output = +""
           @output_bytes = 0
           @buffer = +""
+          @call_mutex.synchronize { @tool_calls = 0 }
           @lifecycle_mutex.synchronize { @generation = generation }
           start_watchdog(generation, @deadline)
           [generation, @session]
@@ -268,20 +271,20 @@ module LittleGhost
         end
 
         def dispatch_call(message, process)
-          thread = @call_mutex.synchronize do
-            active = @call_threads.count(&:alive?)
+          @call_mutex.synchronize do
+            active = @call_tasks.count(&:alive?)
             raise ProtocolError, "code-mode concurrent tool call limit exceeded" if active >= @limits.fetch(:concurrency)
+            @tool_calls += 1
+            raise ToolError, "tool call limit exceeded" if @tool_calls > @limits.fetch(:tool_calls)
 
             call_errors = @call_errors
             closing_marker = @closing_marker
-            Thread.new do
+            @call_tasks << @task_runner.spawn do
               answer_call(message, process, closing_marker)
             rescue => error
               @call_mutex.synchronize { call_errors << error }
             end
           end
-          thread.report_on_exception = false
-          @call_mutex.synchronize { @call_threads << thread }
         end
 
         def append_output(value)
@@ -342,14 +345,14 @@ module LittleGhost
           end
           target, session, sandbox, workspace, directory = claimed
           watchdog = cancel_watchdog(target)
-          threads, call_errors = @call_mutex.synchronize do
-            current_threads = @call_threads
+          tasks, call_errors = @call_mutex.synchronize do
+            current_tasks = @call_tasks
             current_errors = @call_errors
             @closing_marker[:closing] = true
-            @call_threads = []
+            @call_tasks = []
             @call_errors = []
             @closing_marker = {closing: false}
-            [current_threads, current_errors]
+            [current_tasks, current_errors]
           end
           first_error = nil
           begin
@@ -358,17 +361,19 @@ module LittleGhost
             first_error ||= error
           end
           deadline = monotonic_time + @limits.fetch(:cleanup_seconds)
-          threads.each do |thread|
+          tasks.each do |task|
             remaining = deadline - monotonic_time
             break unless remaining.positive?
 
             begin
-              thread.join(remaining)
+              task.wait(deadline: Time.now + remaining)
+            rescue DeadlineExceededError
+              break
             rescue => error
               first_error ||= error
             end
           end
-          if threads.any?(&:alive?)
+          if tasks.any?(&:alive?)
             @closed = true
             first_error ||= CleanupError.new("Code-mode nested tool cleanup timed out")
           end
@@ -389,14 +394,14 @@ module LittleGhost
           rescue => error
             first_error ||= error
           end
-          watchdog&.join unless watchdog.equal?(Thread.current)
+          watchdog&.wait unless watchdog&.current?
           raise first_error if first_error
         end
 
         def start_watchdog(generation, deadline)
           @watchdog_mutex.synchronize do
             @watchdog_generation = generation
-            @watchdog = Thread.new do
+            @watchdog = @task_runner.spawn do
               expired = @watchdog_mutex.synchronize do
                 loop do
                   break false unless @watchdog_generation.equal?(generation)
@@ -411,7 +416,6 @@ module LittleGhost
             rescue => error
               record_program_error(generation, error)
             end
-            @watchdog.report_on_exception = false
           end
         end
 
@@ -419,11 +423,11 @@ module LittleGhost
           @watchdog_mutex.synchronize do
             return unless !generation || @watchdog_generation.equal?(generation)
 
-            thread = @watchdog
+            task = @watchdog
             @watchdog_generation = nil
             @watchdog = nil
             @watchdog_condition.broadcast
-            thread
+            task
           end
         end
 

data/lib/little_ghost/code_mode/ruby_engine.rb

@@ -58,6 +58,7 @@ module LittleGhost
           Output and completion:
           - The final Ruby expression becomes the completed program value.
           - Use `text(value)` for user-visible output.
+          - Ordinary `puts`, `print`, `printf`, and `p` output is captured and combined into bounded chunks.
           - Use `finish(value)` to complete early with a value.
 
           The Sandbox controls filesystem, network, subprocess, and optional-library access. Do not assume host

data/lib/little_ghost/configuration.rb

@@ -33,6 +33,7 @@ module LittleGhost
   class Configuration
     FILE_LOAD_MUTEX = Mutex.new # :nodoc:
     CONFIGURATION_KEYS = %i[invocation service_name].freeze # :nodoc:
+    RUNTIME_BUILD_CONTEXT_KEY = :little_ghost_runtime_build_context # :nodoc:
     DEFAULT_PROMPT_PATHS = ["app/prompts"].freeze # :nodoc:
     DEFAULT_SKILL_PATHS = ["app/skills"].freeze # :nodoc:
     ##
@@ -97,8 +98,18 @@ module LittleGhost
         sandbox: nil,
         code_mode: nil,
         instrumentation_subscribers: [],
-        runtime_hooks: []
+        runtime_hooks: [],
+        concurrency_backend: :auto
       }.merge(values)
+      @configuration_values[:concurrency_backend] = normalize_concurrency_backend(
+        @configuration_values[:concurrency_backend]
+      )
+      if values.key?(:blocking_pool_capacity)
+        Support::Executor.blocking.runner.capacity = normalize_blocking_pool_capacity(
+          values[:blocking_pool_capacity]
+        )
+        @configuration_values.delete(:blocking_pool_capacity)
+      end
       @configuration_values[:prompt_paths] = Array(@configuration_values[:prompt_paths]).dup
       @configuration_values[:skill_paths] = Array(@configuration_values[:skill_paths]).dup
       @configuration_values[:skill_resource_root] = Skills::ResourceRoot.normalize(
@@ -136,11 +147,11 @@ module LittleGhost
     # other writes are rejected. A failed build leaves the configuration
     # editable for a later attempt.
     def runtime
-      build_generation = @lifecycle_monitor.synchronize do
+      build_generation, build_context = @lifecycle_monitor.synchronize do
         loop do
           return @default_runtime if @default_runtime
           if @runtime_building
-            if @runtime_builder_thread.equal?(Thread.current)
+            if current_runtime_build_context.equal?(@runtime_build_context)
               raise ConfigurationError, "LittleGhost.runtime cannot be called while the shared Runtime is starting"
             end
 
@@ -154,14 +165,14 @@ module LittleGhost
             sealed_values = freeze_configuration_copy(@configuration_values)
             @runtime_generation = @runtime_generation.to_i + 1
             @runtime_building = true
-            @runtime_builder_thread = Thread.current
+            @runtime_build_context = Object.new
             @configuration_values = sealed_values
-            break @runtime_generation
+            break [@runtime_generation, @runtime_build_context]
           end
         end
       end
 
-      begin
+      ExecutionState.with(RUNTIME_BUILD_CONTEXT_KEY => build_context) do
         runtime_root = root
         load_file!(root: runtime_root)
         runtime_settings = settings(root: runtime_root)
@@ -186,12 +197,70 @@ module LittleGhost
       ensure
         @lifecycle_monitor.synchronize do
           @runtime_building = false
-          @runtime_builder_thread = nil
+          @runtime_build_context = nil
           @runtime_condition.broadcast
         end
       end
     end
 
+    # Selects how subsequently built runtimes start independent work such as
+    # parallel Tool calls and Workflow branches.
+    #
+    # The default, +:auto+, uses fibers when the caller is already running in a
+    # scheduled fiber and uses threads otherwise. +:thread+ always uses threads.
+    # +:fiber+ raises ConfigurationError when the caller is not in a scheduled
+    # fiber. The application's scheduler must support Fiber.schedule. Any other
+    # value raises ArgumentError.
+    #
+    #   LittleGhost.configure do |config|
+    #     config.concurrency_backend = :thread
+    #   end
+    #
+    # :call-seq:
+    #   concurrency_backend() -> :auto, :thread, :fiber
+    #   concurrency_backend(value) -> :auto, :thread, :fiber
+    def concurrency_backend(value = :__read__)
+      return configuration_values[:concurrency_backend] if value == :__read__
+
+      normalized = normalize_concurrency_backend(value)
+      change_configuration { configuration_values[:concurrency_backend] = normalized }
+      normalized
+    end
+
+    # Replaces the concurrency backend for subsequently built runtimes.
+    def concurrency_backend=(value)
+      concurrency_backend(value)
+    end
+
+    # Returns or sets the maximum number of process-wide workers available to
+    # LittleGhost.offload_blocking, certificate generation, and Filesystem
+    # SessionStore transactions when they run from scheduled fibers. Workers
+    # are created lazily. The default is 2. Every Configuration reads and writes
+    # the same process-wide value.
+    #
+    # Configure this during process startup, before any operation can start the
+    # pool. +value+ must be a positive Integer. Raises ArgumentError for an
+    # invalid value and ConfigurationError when changing the value after the
+    # pool has started.
+    #
+    # :call-seq:
+    #   blocking_pool_capacity() -> integer
+    #   blocking_pool_capacity(value) -> integer
+    def blocking_pool_capacity(value = :__read__)
+      return Support::Executor.blocking.runner.capacity if value == :__read__
+
+      normalized = normalize_blocking_pool_capacity(value)
+      change_configuration do
+        Support::Executor.blocking.runner.capacity = normalized
+      end
+      normalized
+    end
+
+    # Sets the same process-wide worker limit as +blocking_pool_capacity+.
+    def blocking_pool_capacity=(value)
+      blocking_pool_capacity(value)
+    end
+
     # Workspace declaration used for subsequently built runtimes.
     def workspace = configuration_values[:workspace]
     # Sandbox declaration used for subsequently built runtimes.
@@ -419,6 +488,8 @@ module LittleGhost
 
     # Looks up an arbitrary setting by symbol or string-compatible name.
     def [](name)
+      return blocking_pool_capacity if name.to_sym == :blocking_pool_capacity
+
       configuration_values.fetch(name.to_sym)
     end
 
@@ -431,6 +502,10 @@ module LittleGhost
         self.sandbox = value
       when :code_mode
         self.code_mode = value
+      when :concurrency_backend
+        self.concurrency_backend = value
+      when :blocking_pool_capacity
+        self.blocking_pool_capacity = value
       else
         change_configuration { configuration_values[name.to_sym] = value }
       end
@@ -615,7 +690,7 @@ module LittleGhost
 
     def configuration_values
       @lifecycle_monitor.synchronize do
-        if @runtime_building && !@runtime_builder_thread.equal?(Thread.current)
+        if @runtime_building && !current_runtime_build_context.equal?(@runtime_build_context)
           raise_locked_configuration!
         end
 
@@ -701,7 +776,24 @@ module LittleGhost
       return false if @default_runtime
       return true unless @runtime_building
 
-      @configuration_file_loading && @runtime_builder_thread.equal?(Thread.current)
+      @configuration_file_loading && current_runtime_build_context.equal?(@runtime_build_context)
+    end
+
+    def current_runtime_build_context
+      ExecutionState[RUNTIME_BUILD_CONTEXT_KEY]
+    end
+
+    def normalize_concurrency_backend(value)
+      normalized = value.to_sym if value.respond_to?(:to_sym)
+      return normalized if Support::TaskRunner::BACKENDS.include?(normalized)
+
+      raise ArgumentError, "concurrency_backend must be :auto, :thread, or :fiber"
+    end
+
+    def normalize_blocking_pool_capacity(value)
+      return value if value.is_a?(Integer) && value.positive?
+
+      raise ArgumentError, "blocking_pool_capacity must be a positive integer"
     end
 
     def load_configuration_file(path)

data/lib/little_ghost/embeddings/request.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  # Carries provider-neutral inputs and results for text embeddings.
+  #
+  # Applications usually call LittleGhost.embed. Provider adapters receive a
+  # Request and return a Response without exposing provider response objects.
+  module Embeddings
+    DEFAULT_LIMITS = {
+      max_inputs: 128,
+      max_input_bytes: 64 * 1024,
+      max_total_bytes: 1024 * 1024
+    }.freeze # :nodoc:
+
+    Request = Data.define(:inputs, :settings, :limits, :cancellation_token, :deadline) do # :nodoc:
+      # Validates configured budgets before copying retained input strings.
+      def initialize(inputs:, settings: {}, limits: {}, cancellation_token: Support::CancellationToken.new, deadline: nil)
+        values = inputs.is_a?(String) ? [inputs] : inputs
+        unless values.is_a?(Array) && !values.empty? && values.all? { |value| value.is_a?(String) && !value.empty? }
+          raise ArgumentError, "inputs must be a nonempty String or Array of nonempty Strings"
+        end
+        raise ArgumentError, "settings must be a mapping" unless settings.respond_to?(:to_h)
+        raise ArgumentError, "limits must be a mapping" unless limits.respond_to?(:to_h)
+
+        configured_limits = DEFAULT_LIMITS.merge(limits.to_h.transform_keys(&:to_sym))
+        configured_limits.transform_values! { |value| Integer(value) }
+        unless configured_limits.values.all?(&:positive?)
+          raise ArgumentError, "embedding limits must be positive integers"
+        end
+        if values.length > configured_limits.fetch(:max_inputs)
+          raise UnsupportedInputError, "Embedding input count exceeds the configured limit"
+        end
+        total_bytes = 0
+        values.each do |value|
+          bytes = value.bytesize
+          if bytes > configured_limits.fetch(:max_input_bytes)
+            raise UnsupportedInputError, "An embedding input exceeds the configured byte limit"
+          end
+          total_bytes += bytes
+          if total_bytes > configured_limits.fetch(:max_total_bytes)
+            raise UnsupportedInputError, "Embedding inputs exceed the configured aggregate byte limit"
+          end
+        end
+
+        super(
+          inputs: values.map { |value| value.dup.freeze }.freeze,
+          settings: settings.to_h.transform_keys(&:to_sym).freeze,
+          limits: configured_limits.freeze,
+          cancellation_token:,
+          deadline:
+        )
+      end
+    end
+
+    # Carries the validated inputs and controls for one embedding operation.
+    #
+    # LittleGhost builds this value for LittleGhost.embed and passes it to the
+    # selected provider. Provider implementations may receive calls
+    # concurrently. They must observe +cancellation_token+ and +deadline+ while
+    # performing external work.
+    class Request < Data # :doc:
+      ##
+      # :singleton-method: new
+      # :call-seq:
+      #   new(inputs:, settings: {}, limits: {}, cancellation_token: Support::CancellationToken.new, deadline: nil) -> Request
+      #
+      # Validates and freezes one String or a nonempty Array of Strings.
+      #
+      # +settings+ contains trusted model settings. +limits+ may override the
+      # input budgets:
+      #
+      # [+:max_inputs+]
+      #   Number of input strings. Defaults to 128.
+      # [+:max_input_bytes+]
+      #   Bytes allowed in one input. Defaults to 64 KiB.
+      # [+:max_total_bytes+]
+      #   Bytes allowed across all inputs. Defaults to 1 MiB.
+      #
+      # Invalid shapes raise ArgumentError; inputs outside these budgets raise
+      # UnsupportedInputError.
+
+      ##
+      # :attr_reader: inputs
+      # Frozen input strings in caller order.
+
+      ##
+      # :attr_reader: settings
+      # Frozen model settings chosen by trusted application code.
+
+      ##
+      # :attr_reader: limits
+      # Frozen input budgets applied before LittleGhost retains the strings.
+
+      ##
+      # :attr_reader: cancellation_token
+      # Token that stops the provider operation when cancellation is requested.
+
+      ##
+      # :attr_reader: deadline
+      # Monotonic deadline for the provider operation, or +nil+.
+    end
+  end
+end

data/lib/little_ghost/embeddings/response.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  module Embeddings
+    Response = Data.define(:vectors, :usage, :metadata) do # :nodoc:
+      # Validates finite, consistently sized numeric vectors and freezes them.
+      def initialize(vectors:, usage: Usage.new, metadata: {})
+        values = Array(vectors)
+        unless !values.empty? && values.all? { |vector| vector.is_a?(Array) && !vector.empty? }
+          raise ProtocolError, "Embedding provider returned no vectors"
+        end
+        dimensions = values.first.length
+        unless values.all? { |vector| vector.length == dimensions && vector.all? { |number| number.is_a?(Numeric) && (!number.respond_to?(:finite?) || number.finite?) } }
+          raise ProtocolError, "Embedding provider returned invalid vectors"
+        end
+
+        frozen_vectors = values.map { |vector| vector.map(&:to_f).freeze }.freeze
+        super(vectors: frozen_vectors, usage:, metadata: metadata.to_h.merge(dimensions:).freeze)
+      end
+
+      # Number of numeric values in each vector.
+      def dimensions = metadata.fetch(:dimensions)
+    end
+
+    # Carries validated embedding vectors without provider response objects.
+    #
+    # Vectors are finite, consistently sized, frozen, and ordered like the
+    # corresponding Request inputs. LittleGhost raises ProtocolError instead of
+    # returning an invalid or partial provider response.
+    class Response < Data # :doc:
+      ##
+      # :singleton-method: new
+      # :call-seq:
+      #   new(vectors:, usage: Usage.new, metadata: {}) -> Response
+      #
+      # Validates and freezes provider-neutral vectors, usage, and metadata.
+
+      ##
+      # :attr_reader: vectors
+      # Frozen numeric vectors in request-input order.
+
+      ##
+      # :attr_reader: usage
+      # Normalized provider usage for the operation.
+
+      ##
+      # :attr_reader: metadata
+      # Frozen operation metadata, including +dimensions+.
+
+      ##
+      # :method: dimensions
+      # Number of numeric values in each vector.
+    end
+  end
+end

data/lib/little_ghost/errors.rb

@@ -36,6 +36,8 @@ module LittleGhost
   class AssemblyStepTimeoutError < AssemblyError; end
   # Raised when an invocation contains an unsupported input form.
   class UnsupportedInputError < InvocationError; end
+  # Raised when a provider does not implement the requested model operation.
+  class UnsupportedModelOperationError < ConfigurationError; end
   # Base class for provider request, response, and protocol failures. Agent Runs
   # normally record these as failed outcomes; provider retry policy may handle a
   # retryable failure before it reaches the Run.