little_ghost 0.5.0 → 0.7.0

data/lib/little_ghost/execution.rb

@@ -1,8 +1,8 @@
 # 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.
+  # Runs one dormant Run in the background while the caller remains free to
+  # serve health checks, deliver interjections, or coordinate shutdown.
   #
   #   execution = agent.start_execution(message: "Investigate transfer 481") do |event|
   #     event_buffer << event
@@ -12,21 +12,24 @@ module LittleGhost
   #   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,
+  # The Runtime selects a scheduled fiber or worker thread for the execution.
+  # LittleGhost copies the caller's ExecutionState, but not other application
+  # fiber-local or thread-local values. 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
+  # cooperative cancellation and waits for the execution and any in-flight
   # interjection calls.
   class Execution
     # The supervised Run.
     attr_reader :run
 
     class << self
-      # Starts +run+ immediately and returns its supervising Execution.
+      # Starts +run+ immediately and returns its supervising Execution. If the
+      # work cannot start, this method closes +run+ before raising.
       #
-      # 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.
+      # The optional block receives each StreamEvent from the fiber or thread
+      # running the Execution. It must not depend on a particular thread and
+      # should not pause the scheduler or retain sensitive event content longer
+      # than the application requires.
       def start(run, &event_consumer)
         new(run, event_consumer:).send(:start)
       end
@@ -41,12 +44,11 @@ module LittleGhost
       @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
+      @task_runner = run.runtime.task_runner
     end
 
     # Returns +:pending+, +:running+, or +:finished+.
@@ -54,17 +56,17 @@ module LittleGhost
       @mutex.synchronize { @state }
     end
 
-    # Returns an event-delivery or cleanup exception raised by the worker.
+    # Returns an event-delivery or cleanup exception raised by the Execution.
     def error
-      @mutex.synchronize { @error }
+      @mutex.synchronize { @worker }&.error
     end
 
-    # Indicates that the worker or an interjection call is still active.
+    # Indicates that the Execution 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.
+    # Indicates that the Execution and all interjection calls have finished.
     def finished?
       !active?
     end
@@ -97,15 +99,15 @@ module LittleGhost
       self
     end
 
-    # Waits for the worker and in-flight interjections, then returns the Run.
+    # Waits for the Execution 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.
+    # the Execution is re-raised after all supervised work finishes.
     def wait(deadline: nil)
       worker = wait_until_finished(deadline:)
-      worker.join
-      caught = error
+      worker.wait
+      caught = worker.error
       raise caught if caught
 
       run
@@ -126,19 +128,23 @@ module LittleGhost
         raise Error, "execution has already started" unless @state == :pending
 
         @state = :running
-        @worker = Thread.new { execute }
       end
+      worker = @task_runner.spawn { execute }
+      @mutex.synchronize { @worker = worker }
       self
+    rescue
+      @mutex.synchronize do
+        @state = :finished
+        @condition.broadcast
+      end
+      run.close
+      raise
     end
 
     private
 
     def execute
-      ExecutionState.with(@execution_state) do
-        run.each { |event| @event_consumer&.call(event) }
-      end
-    rescue => caught
-      @mutex.synchronize { @error = caught }
+      run.each { |event| @event_consumer&.call(event) }
     ensure
       @mutex.synchronize do
         @state = :finished

data/lib/little_ghost/execution_state.rb

@@ -1,9 +1,9 @@
 # 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.
+  # ExecutionState carries request-scoped values across scheduled fibers and
+  # worker threads. 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

data/lib/little_ghost/graph.rb

@@ -808,9 +808,12 @@ module LittleGhost
       deadline:, settings:, template_locals:, template_paths:, parent_operation_id:, events:)
       token = cancellation_token.child
       queue = SizedQueue.new(1_000)
-      worker = Thread.new do
+      worker = task_runner.spawn do
         completed = []
-        results = Support::Executor.new(max_concurrency: fork.max_concurrency).map(
+        results = Support::Executor.new(
+          max_concurrency: fork.max_concurrency,
+          runner: task_runner
+        ).map(
           fork.to,
           cancellation_token: token,
           on_result: ->(_index, result) { completed << result }
@@ -840,7 +843,7 @@ module LittleGhost
       end
     ensure
       token&.cancel
-      worker&.join
+      worker&.wait
     end
 
     def run_graph_branch(start:, source:, source_step_id:, join:, nodes:, edges:,

data/lib/little_ghost/instrumentation.rb

@@ -33,7 +33,8 @@ module LittleGhost
     # Override the callbacks a backend supports. +start+ and +finish+ receive the
     # same operation name and correlated attributes. +emit+ receives point
     # events. Implementations may return a propagation carrier from
-    # #trace_context. Callbacks should be thread-safe.
+    # #trace_context. Calls may overlap on threads or fibers, so implementations
+    # must protect shared mutable state without relying on thread identity.
     class Subscriber
       # Called when a lifecycle operation starts.
       def start(_name, _attributes) = nil

data/lib/little_ghost/mcp/toolset.rb

@@ -111,7 +111,7 @@ module LittleGhost
         # Generates Tool classes for an Agent's current binding.
         def tools(binding)
           options = resolved_connection(binding)
-          context = binding.run.context if binding.run&.respond_to?(:context)
+          context = binding.run&.context
           mapper = tool_mapping_value
           result_mapper = result_mapping_value
           options = connection_with_wrapped_signer(options)

data/lib/little_ghost/model.rb

@@ -76,6 +76,26 @@ module LittleGhost
       provider.stream(configured_request, &block)
     end
 
+    # Applies profile settings and executes an Embeddings::Request.
+    #
+    # Returns an Embeddings::Response with one vector per input. A provider that
+    # returns another shape raises ProtocolError.
+    def embed(request)
+      configured = Embeddings::Request.new(
+        inputs: request.inputs,
+        settings: settings.merge(request.settings),
+        limits: request.limits,
+        cancellation_token: request.cancellation_token,
+        deadline: request.deadline
+      )
+      response = provider.embed(configured)
+      unless response.is_a?(Embeddings::Response) && response.vectors.length == configured.inputs.length
+        raise ProtocolError, "Embedding provider returned an unexpected vector count"
+      end
+
+      response
+    end
+
     # Uses advertised provider capabilities.
     def capabilities
       @capabilities ||= provider.capabilities(metadata: details.attributes)

data/lib/little_ghost/model_operations.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require "json"
+
+module LittleGhost
+  # Executes bounded model operations without creating an Agent or Run.
+  class ModelOperations # :nodoc:
+    MAX_STRUCTURED_RESULT_BYTES = 1_000_000
+    MAX_STRUCTURED_RESULT_DEPTH = 64
+    MAX_STRUCTURED_RESULT_NODES = 100_000
+    MAX_STRUCTURED_RESULT_REPAIR_ATTEMPTS = 3
+
+    def initialize(model_resolver:)
+      @model_resolver = model_resolver
+    end
+
+    def generate(model:, messages:, result_schema: nil, settings: {}, structured_result_repair_attempts: 1, cancellation_token: Support::CancellationToken.new, deadline: nil)
+      resolved = @model_resolver.resolve(model)
+      schema = normalize_schema(result_schema)
+      repair_attempts = normalize_repair_attempts(structured_result_repair_attempts) if schema
+      strategy = StructuredOutput.resolve(schema, model: resolved, ordinary_tools: []) if schema
+      handle = Instrumentation.start(:generation, model_provider: resolved.target.provider, model_id: resolved.model_id, model_role: resolved.role, structured: !schema.nil?)
+      usage = Usage.new
+      conversation = messages.map { |message| Message.coerce(message) }
+      response = complete(resolved, messages: conversation, settings:, schema:, strategy:, repair: false, cancellation_token:, deadline:)
+      usage += response.usage
+      output, errors = schema ? parse_structured_response(response.message, schema, strategy) : [response.message.text, []]
+      conversation << (schema ? redact_structured_response(response.message, schema, strategy) : response.message)
+      repairs_remaining = repair_attempts
+      while schema && !errors.empty? && repairs_remaining.positive?
+        conversation << structured_repair_message(response.message, strategy, errors:, repairs_remaining:)
+        response = complete(resolved, messages: conversation, settings:, schema:, strategy:, repair: true, cancellation_token:, deadline:)
+        usage += response.usage
+        output, errors = parse_structured_response(response.message, schema, strategy)
+        conversation << redact_structured_response(response.message, schema, strategy)
+        repairs_remaining -= 1
+      end
+      unless errors.empty?
+        raise StructuredResultError.new(
+          "The model did not return a valid structured result after its repair attempts",
+          schema_name: schema.fetch(:name), validation_errors: errors
+        )
+      end
+      handle.finish(outcome: :success, **usage_attributes(usage))
+      structured_result = StructuredResult.new(schema_name: schema.fetch(:name), value: output) if schema
+      final_message = schema ? conversation.last : response.message
+      RunResult.new(
+        message: final_message,
+        stop_reason: schema ? :structured_result : response.stop_reason,
+        usage:,
+        messages: conversation.freeze,
+        state: DataMap.new,
+        structured_result:,
+        steps: []
+      )
+    rescue => error
+      handle&.finish(outcome: :error, error_type: error.class.name) if handle&.active?
+      raise
+    end
+
+    def embed(model:, inputs:, settings: {}, limits: {}, cancellation_token: Support::CancellationToken.new, deadline: nil)
+      request = Embeddings::Request.new(inputs:, settings:, limits:, cancellation_token:, deadline:)
+      resolved = @model_resolver.resolve(model)
+      handle = Instrumentation.start(:embedding, model_provider: resolved.target.provider, model_id: resolved.model_id, model_role: resolved.role, input_count: request.inputs.length)
+      response = resolved.embed(request)
+      metadata = response.metadata.merge(provider: resolved.target.provider, model: resolved.model_id, model_role: resolved.role, input_count: request.inputs.length).compact
+      result = Embeddings::Response.new(vectors: response.vectors, usage: response.usage, metadata:)
+      handle.finish(outcome: :success, dimensions: result.dimensions, **usage_attributes(result.usage))
+      result
+    rescue => error
+      handle&.finish(outcome: :error, error_type: error.class.name) if handle&.active?
+      raise
+    end
+
+    private
+
+    def complete(model, messages:, settings:, schema:, strategy:, repair:, cancellation_token:, deadline:)
+      request = ModelRequest.new(
+        messages:, settings:,
+        tools: strategy ? strategy.tools([]) : [],
+        output_schema: strategy&.output_schema,
+        tool_choice: direct_generation_tool_choice(strategy, repair:),
+        required_capabilities: strategy ? strategy.required_capabilities : [],
+        cancellation_token:, deadline:
+      )
+      response = nil
+      model.stream(request) do |event|
+        response = event.data[:response] if event.type == :message_stop
+      end
+      response || raise(ProtocolError, "Provider stream ended without a response")
+    end
+
+    def normalize_schema(value)
+      return unless value
+      raise ArgumentError, "result_schema must be a mapping" unless value.respond_to?(:to_h)
+
+      schema = value.to_h.transform_keys(&:to_sym)
+      name = schema.fetch(:name).to_s
+      json_schema = schema.fetch(:schema)
+      Class.new(Agent).result_schema(
+        json_schema,
+        name:,
+        description: schema[:description],
+        strategy: :auto
+      ).except(:strategy).freeze
+    end
+
+    def parse_structured_response(message, schema, strategy)
+      return parse_structured(message.text, schema) if strategy.provider?
+
+      tool_uses = message.content.grep(Content::ToolUse)
+      result_tool_uses = tool_uses.select { |tool_use| tool_use.name == strategy.schema_name }
+      return [nil, ["The structured result tool was not called"]] if result_tool_uses.empty?
+      return [nil, ["The model called the structured result tool more than once"]] if result_tool_uses.length > 1
+      return [nil, ["The structured result tool must be the only tool call in its response"]] if tool_uses.length > 1
+
+      validate_structured_value(result_tool_uses.first.input, schema)
+    end
+
+    def parse_structured(text, schema)
+      raise StructuredResultError.new("Structured result exceeds the maximum serialized size", schema_name: schema.fetch(:name)) if text.bytesize > MAX_STRUCTURED_RESULT_BYTES
+      value = JSON.parse(text)
+      validate_structured_value(value, schema)
+    rescue JSON::ParserError
+      [nil, ["Structured result is not valid JSON"]]
+    rescue StructuredResultError => error
+      [nil, [error.message]]
+    end
+
+    def validate_structured_value(value, schema)
+      validate_complexity!(value, schema.fetch(:name))
+      errors = Tool::SchemaValidator.new(schema.fetch(:schema)).validate(value)
+      [value, errors]
+    rescue StructuredResultError => error
+      [nil, [error.message]]
+    end
+
+    def structured_repair_message(message, strategy, errors:, repairs_remaining:)
+      tool_uses = message.content.grep(Content::ToolUse)
+      feedback = "The structured result did not match the required schema: #{errors.join("; ")}. Submit it again using the required schema."
+      if strategy.tool? && !tool_uses.empty?
+        return Message.new(
+          role: :tool,
+          content: tool_uses.map do |tool_use|
+            Content::ToolResult.new(
+              tool_use_id: tool_use.id,
+              content: feedback,
+              status: :error
+            )
+          end
+        )
+      end
+
+      requirement = strategy.tool? ? "Call #{strategy.schema_name} exactly once as your only tool call." : "Return only JSON matching the configured output schema."
+      attempts_description = (repairs_remaining == 1) ? "one repair attempt" : "#{repairs_remaining} repair attempts"
+      Message.new(role: :user, content: "#{requirement} You have #{attempts_description} remaining. #{feedback}")
+    end
+
+    def direct_generation_tool_choice(strategy, repair:)
+      return unless strategy
+      return {name: strategy.schema_name}.freeze if strategy.tool?
+
+      strategy.tool_choice(repair:)
+    end
+
+    def normalize_repair_attempts(value)
+      return value if value.is_a?(Integer) && value.between?(0, MAX_STRUCTURED_RESULT_REPAIR_ATTEMPTS)
+
+      raise ArgumentError, "structured_result_repair_attempts must be an integer from zero through #{MAX_STRUCTURED_RESULT_REPAIR_ATTEMPTS}"
+    end
+
+    def validate_complexity!(value, schema_name)
+      nodes = 0
+      stack = [[value, 1]]
+      until stack.empty?
+        child, depth = stack.pop
+        nodes += 1
+        raise StructuredResultError.new("Structured result exceeds the maximum nesting depth", schema_name:) if depth > MAX_STRUCTURED_RESULT_DEPTH
+        raise StructuredResultError.new("Structured result exceeds the maximum complexity", schema_name:) if nodes > MAX_STRUCTURED_RESULT_NODES
+        child.each { |key, nested| stack << [key, depth + 1] << [nested, depth + 1] } if child.is_a?(Hash)
+        child.each { |nested| stack << [nested, depth + 1] } if child.is_a?(Array)
+      end
+    end
+
+    def redact_structured_message(message, schema)
+      Message.new(
+        role: message.role,
+        content: "[Structured result #{schema.fetch(:name)} redacted]",
+        metadata: message.metadata
+      )
+    end
+
+    def redact_structured_response(message, schema, strategy)
+      tool_uses = message.content.grep(Content::ToolUse)
+      return redact_structured_message(message, schema) unless strategy.tool? && !tool_uses.empty?
+
+      Message.new(
+        role: message.role,
+        content: tool_uses.map do |tool_use|
+          Content::ToolUse.new(id: tool_use.id, name: tool_use.name, input: {})
+        end,
+        metadata: message.metadata
+      )
+    end
+
+    def usage_attributes(usage)
+      usage.to_h.except(:total_tokens)
+    end
+  end
+end

data/lib/little_ghost/network/certificate_authority.rb

@@ -10,6 +10,12 @@ module LittleGhost
       module_function
 
       def create(root:, hosts:, trust_root: File.join(root, "trust"))
+        LittleGhost.offload_blocking do
+          create_material(root:, hosts:, trust_root:)
+        end
+      end
+
+      def create_material(root:, hosts:, trust_root:)
         Dir.mkdir(trust_root, 0o700) unless Dir.exist?(trust_root)
         ca_key = OpenSSL::PKey::RSA.new(3072)
         ca_certificate = certificate(

data/lib/little_ghost/network/envoy_gateway.rb

@@ -307,13 +307,22 @@ module LittleGhost
 
         Process.kill("TERM", -@envoy_pid)
         deadline = monotonic_time + 2
+        finished = nil
         until monotonic_time >= deadline
           finished = Process.waitpid(@envoy_pid, Process::WNOHANG)
           break if finished
           sleep(0.01)
         end
-        Process.kill("KILL", -@envoy_pid)
-        Process.waitpid(@envoy_pid)
+        unless finished
+          Process.kill("KILL", -@envoy_pid)
+          deadline = monotonic_time + 2
+          until Process.waitpid(@envoy_pid, Process::WNOHANG)
+            if monotonic_time >= deadline
+              raise CleanupError, "Envoy did not exit after it was killed"
+            end
+            sleep(0.01)
+          end
+        end
       rescue Errno::ESRCH, Errno::ECHILD
         nil
       ensure

data/lib/little_ghost/providers/base.rb

@@ -21,7 +21,12 @@ module LittleGhost
     end
 
     # Shared provider contract. Provider adapters implement #stream and may
-    # override capability-sensitive request preparation.
+    # implement #embed or override capability-sensitive request preparation.
+    #
+    # LittleGhost may call one provider instance concurrently. An embedding
+    # adapter accepts Embeddings::Request, observes its cancellation and
+    # deadline, and returns Embeddings::Response. Provider failures should use a
+    # content-safe ProviderError subclass.
     class Base
       # Returns the trusted per-profile request options this adapter accepts.
       # Connection options remain authoritative and are configured separately.
@@ -32,6 +37,16 @@ module LittleGhost
         raise AbstractMethodError, "#{self.class} must implement #stream"
       end
 
+      # Executes +request+ when the adapter supports text embeddings.
+      #
+      # The default implementation raises UnsupportedModelOperationError.
+      #
+      # :call-seq:
+      #   embed(request) -> Embeddings::Response
+      def embed(_request)
+        raise UnsupportedModelOperationError, "#{self.class} does not support embeddings"
+      end
+
       # Applies provider-specific capability constraints before streaming.
       def prepare_request(request, capabilities:)
         request

data/lib/little_ghost/providers/bedrock/aws_protocol.rb

@@ -45,7 +45,7 @@ module LittleGhost
 
         def canonical_path(uri)
           path = uri.path.empty? ? "/" : uri.path
-          path.split("/", -1).map { |part| URI.encode_www_form_component(URI.decode_www_form_component(part)).gsub("+", "%20") }.join("/")
+          path.split("/", -1).map { |part| URI.encode_www_form_component(part).gsub("+", "%20") }.join("/")
         end
 
         def canonical_query(uri)

data/lib/little_ghost/providers/bedrock/http_client.rb

@@ -10,6 +10,7 @@ module LittleGhost
       # the adapter.
       class HTTPClient # :nodoc:
         Response = Data.define(:stream)
+        InvokeResponse = Data.define(:body)
         DEFAULT_MAX_RESPONSE_BYTES = 256 * 1024 * 1024
 
         def initialize(region:, credentials: nil, credential_resolver: nil, endpoint: nil,
@@ -44,33 +45,53 @@ module LittleGhost
           Response.new(stream:)
         end
 
+        def invoke_model(model_id:, body:, max_response_bytes:, cancellation_token: nil, deadline: nil)
+          payload = JSON.generate(camelize(body))
+          uri = URI.join(@endpoint.to_s, "/model/#{escape_path(model_id)}/invoke")
+          credentials = @credential_resolver.call
+          signer = AwsSigV4.new(service: "bedrock", region: @region, credentials:, clock: @clock)
+          headers = signer.headers(method: :post, uri:, headers: {"content-type" => "application/json", "accept" => "application/json"}, body: payload)
+          response = @http_client.request(
+            uri:, method: :post, headers:, body: payload,
+            cancellation_token:, deadline:, label: "Bedrock request", max_response_bytes:
+          )
+          InvokeResponse.new(body: response)
+        end
+
         private
 
         def event(headers, payload)
           value = payload.empty? ? {} : JSON.parse(payload)
           type = headers[":event-type"] || headers[":exception-type"]
-          {type.to_s.gsub(/([a-z])([A-Z])/, "\\1_\\2").downcase.to_sym => symbolize(value)}
+          {underscore(type).to_sym => normalize_event_payload(value)}
         rescue JSON::ParserError => error
           raise ProtocolError, "Bedrock returned invalid event JSON: #{error.message}"
         end
 
-        def camelize(value)
+        def camelize(value, json_schema: false, input_schema: false)
           case value
           when Hash
-            value.to_h { |key, child| [key.to_s.gsub(/_([a-z])/) { Regexp.last_match(1).upcase }, camelize(child)] }
-          when Array then value.map { |child| camelize(child) }
+            value.to_h do |key, child|
+              key = key.to_s
+              [json_schema ? key : camelize_key(key), camelize(child, json_schema: json_schema || (input_schema && key == "json"), input_schema: key == "input_schema")]
+            end
+          when Array then value.map { |child| camelize(child, json_schema:, input_schema: false) }
           else value
           end
         end
 
-        def symbolize(value)
+        def camelize_key(key) = key.gsub(/_([a-z])/) { Regexp.last_match(1).upcase }
+
+        def normalize_event_payload(value)
           case value
-          when Hash then value.to_h { |key, child| [key.to_sym, symbolize(child)] }
-          when Array then value.map { |child| symbolize(child) }
+          when Hash then value.to_h { |key, child| [underscore(key).to_sym, normalize_event_payload(child)] }
+          when Array then value.map { |child| normalize_event_payload(child) }
           else value
           end
         end
 
+        def underscore(value) = value.to_s.gsub(/([a-z0-9])([A-Z])/, "\\1_\\2").downcase
+
         def escape_path(value) = URI.encode_www_form_component(value.to_s).gsub("+", "%20")
       end
     end