little_ghost 0.5.0 → 0.7.0

data/lib/little_ghost/providers/bedrock.rb

@@ -11,9 +11,9 @@ module LittleGhost
   # request and response types. Agents select them through model configuration rather
   # than depending on a provider class directly.
   module Providers
-    # Bedrock lets LittleGhost agents use models available through Amazon Bedrock
-    # Converse. Its output follows the same streaming events as every other
-    # LittleGhost provider.
+    # Bedrock lets LittleGhost features use models available through Amazon
+    # Bedrock. Generation uses Converse and follows the same streaming events as
+    # every other LittleGhost provider.
     #
     #   provider = LittleGhost::Providers::Bedrock.new(
     #     model: ENV.fetch("BEDROCK_MODEL_ID"),
@@ -34,6 +34,7 @@ module LittleGhost
 
       INITIAL_RETRY_DELAY = 1 # :nodoc:
       MAX_RETRY_DELAY = 16 # :nodoc:
+      DEFAULT_MAX_EMBEDDING_RESPONSE_BYTES = 8 * 1024 * 1024 # :nodoc:
       TRANSIENT_STREAM_ERRORS = %w[
         internal_server_exception model_stream_error_exception service_unavailable_exception throttling_exception
       ].freeze # :nodoc:
@@ -63,15 +64,17 @@ module LittleGhost
       # Configures Bedrock for +model+.
       #
       # +region+ and remaining +client_options+ configure the built-in HTTP client.
-      # +max_retries+, +sleeper+, and +on_retry+ control retry behavior. Injecting
-      # +client+ bypasses creation of the built-in HTTP client.
+      # +max_retries+, +sleeper+, and +on_retry+ control retry behavior.
+      # +max_embedding_response_bytes+ bounds each embedding response retained in
+      # memory. Injecting +client+ bypasses creation of the built-in HTTP client.
       def initialize(model:, region: nil, client: nil, max_retries: 2, sleeper: nil,
-        on_retry: ->(*) {}, **client_options)
+        on_retry: ->(*) {}, max_embedding_response_bytes: DEFAULT_MAX_EMBEDDING_RESPONSE_BYTES, **client_options)
         @model = model
         @client = client || build_client(region:, **client_options)
         @max_retries = Integer(max_retries)
         @sleeper = sleeper
         @on_retry = on_retry
+        @max_embedding_response_bytes = positive_integer(max_embedding_response_bytes, :max_embedding_response_bytes)
       end
 
       # Streams LittleGhost StreamEvent objects for +request+.
@@ -132,6 +135,49 @@ module LittleGhost
         end
       end
 
+      # Embeds text with Amazon Titan Text Embeddings V2.
+      #
+      # The +:dimensions+ request setting accepts 256, 512, or 1024 and defaults
+      # to 1024. +:normalize+ controls vector normalization and defaults to true.
+      # Inputs are requested sequentially, and a failure raises without returning
+      # a partial batch.
+      def embed(request)
+        unless model == "amazon.titan-embed-text-v2:0"
+          raise UnsupportedModelOperationError, "Bedrock embeddings require amazon.titan-embed-text-v2:0"
+        end
+
+        dimensions = Integer(request.settings.fetch(:dimensions, 1024))
+        raise ConfigurationError, "dimensions must be 256, 512, or 1024" unless [256, 512, 1024].include?(dimensions)
+        normalize = request.settings.fetch(:normalize, true)
+        unless normalize == true || normalize == false
+          raise ConfigurationError, "normalize must be true or false"
+        end
+
+        vectors = []
+        usage = Usage.new
+        request.inputs.each do |input|
+          response = with_retries(request) do
+            @client.invoke_model(
+              model_id: model,
+              body: {input_text: input, dimensions:, normalize:},
+              cancellation_token: request.cancellation_token,
+              deadline: request.deadline,
+              max_response_bytes: @max_embedding_response_bytes
+            )
+          end
+          payload = JSON.parse(response.body)
+          vector = payload.fetch("embedding")
+          unless vector.is_a?(Array) && vector.length == dimensions
+            raise ProtocolError, "Bedrock returned an embedding with unexpected dimensions"
+          end
+          vectors << vector
+          usage += Usage.new(input_tokens: payload["inputTextTokenCount"])
+        rescue JSON::ParserError, KeyError
+          raise ProtocolError, "Bedrock returned an invalid embedding response"
+        end
+        Embeddings::Response.new(vectors:, usage:, metadata: {model:})
+      end
+
       # Reads capabilities from Bedrock +supported_parameters+ metadata. Missing
       # metadata produces ModelCapabilities.unknown.
       def capabilities(metadata: {})
@@ -149,6 +195,29 @@ module LittleGhost
 
       private
 
+      def positive_integer(value, name)
+        integer = Integer(value)
+        raise ArgumentError, "#{name} must be positive" unless integer.positive?
+
+        integer
+      end
+
+      def with_retries(request)
+        attempts = 0
+        begin
+          request.cancellation_token.raise_if_cancelled!
+          yield
+        rescue HTTPError => error
+          raise unless error.retryable? && attempts < @max_retries
+
+          attempts += 1
+          delay = capped_retry_delay(request, retry_delay(attempts))
+          @on_retry.call(attempts, error, delay)
+          wait_before_retry(request, delay)
+          retry
+        end
+      end
+
       def build_client(region:, **options)
         resolver = options.delete(:credential_resolver)
         resolver ||= CredentialResolver.new
@@ -261,9 +330,8 @@ module LittleGhost
         tool_spec = {
           name: definition.fetch(:name),
           description: definition[:description],
-          input_schema: {json: definition[:input_schema] || {}}
+          input_schema: {json: bedrock_tool_schema(definition[:input_schema] || {})}
         }
-        tool_spec[:strict] = definition[:strict] unless definition[:strict].nil?
         {
           tool_spec: {
             **tool_spec
@@ -277,6 +345,18 @@ module LittleGhost
         {tool: {name: choice.fetch(:name).to_s}}
       end
 
+      def bedrock_tool_schema(schema)
+        return schema unless nova_model?
+
+        schema.to_h.each_with_object({}) do |(key, value), result|
+          result[key] = value if %w[type properties required].include?(key.to_s)
+        end
+      end
+
+      def nova_model?
+        model.match?(/(?:^|\.)amazon\.nova(?:[-.])/)
+      end
+
       def extract_settings(settings, keys)
         keys.each_with_object({}) do |key, result|
           value = settings[key] || settings[key.to_s]
@@ -409,6 +489,10 @@ module LittleGhost
           raise ProtocolError, "Bedrock stream ended before message_stop" unless @terminal
 
           @finished = true
+          if @stop_reason == :malformed_tool_use
+            raise MalformedToolCallError, "Bedrock returned malformed_tool_use"
+          end
+
           blocks = []
           @reasoning_blocks.sort.each do |_index, reasoning|
             if !reasoning[:redacted_content].empty?
@@ -503,6 +587,7 @@ module LittleGhost
         def normalize_stop(value)
           case value
           when "tool_use" then :tool_use
+          when "malformed_tool_use" then :malformed_tool_use
           when "max_tokens" then :max_tokens
           when "guardrail_intervened", "content_filtered" then :content_filter
           else :end_turn

data/lib/little_ghost/providers/openai.rb

@@ -4,8 +4,9 @@ require_relative "openai_compatible"
 
 module LittleGhost
   module Providers
-    # OpenAI connects LittleGhost agents to OpenAI models with streaming, tools,
-    # and structured results. It uses the Responses API by default.
+    # OpenAI connects LittleGhost features to OpenAI models for generation and
+    # embeddings. Generation uses the Responses API by default and supports
+    # streaming, Tools, and structured results.
     #
     #   provider = LittleGhost::Providers::OpenAI.new(
     #     api_key: ENV.fetch("OPENAI_API_KEY"),
@@ -17,10 +18,85 @@ module LittleGhost
     class OpenAI < OpenAICompatible
       # The OpenAI API endpoint used when +base_url+ is omitted.
       DEFAULT_BASE_URL = "https://api.openai.com/v1/"
+      DEFAULT_MAX_EMBEDDING_RESPONSE_BYTES = 8 * 1024 * 1024 # :nodoc:
 
       # Uses the official OpenAI API base URL by default.
-      def initialize(base_url: DEFAULT_BASE_URL, **arguments)
-        super
+      #
+      # +max_embedding_response_bytes+ bounds the response retained for one
+      # embedding batch. Remaining +arguments+ configure the shared generation
+      # transport and retry behavior.
+      def initialize(base_url: DEFAULT_BASE_URL, max_embedding_response_bytes: DEFAULT_MAX_EMBEDDING_RESPONSE_BYTES, **arguments)
+        @max_embedding_response_bytes = Integer(max_embedding_response_bytes)
+        raise ArgumentError, "max_embedding_response_bytes must be positive" unless @max_embedding_response_bytes.positive?
+
+        super(base_url:, **arguments)
+      end
+
+      # Embeds one or more strings with the configured OpenAI model.
+      #
+      # The optional +:dimensions+ request setting selects a supported output
+      # size for models that accept it. The response preserves input order and
+      # raises ProtocolError when OpenAI returns an incomplete or invalid batch.
+      def embed(request)
+        attempts = 0
+        begin
+          request.cancellation_token.raise_if_cancelled!
+          payload = {
+            model:,
+            input: request.inputs,
+            encoding_format: "float"
+          }
+          dimensions = request.settings[:dimensions]
+          payload[:dimensions] = Integer(dimensions) if dimensions
+          body = +""
+          @transport.stream(
+            path: "embeddings",
+            headers: {"Authorization" => "Bearer #{@api_key}", "Content-Type" => "application/json"}.merge(@headers),
+            body: JSON.generate(payload),
+            cancellation_token: request.cancellation_token,
+            deadline: request.deadline
+          ) do |chunk|
+            if body.bytesize + chunk.bytesize > @max_embedding_response_bytes
+              raise ProtocolError, "OpenAI embedding response exceeded #{@max_embedding_response_bytes} bytes"
+            end
+            body << chunk
+          end
+          normalize_embedding_response(body, request.inputs.length, dimensions && Integer(dimensions))
+        rescue HTTPError => error
+          raise unless error.retryable? && attempts < @max_retries
+
+          attempts += 1
+          delay = capped_retry_delay(request, retry_delay(attempts))
+          @on_retry.call(attempts, error, delay)
+          wait_before_retry(request, delay)
+          retry
+        end
+      end
+
+      private
+
+      def normalize_embedding_response(body, input_count, expected_dimensions)
+        payload = JSON.parse(body)
+        data = payload.fetch("data")
+        raise ProtocolError, "OpenAI returned an invalid embedding count" unless data.is_a?(Array) && data.length == input_count
+
+        ordered = data.sort_by { |item| Integer(item.fetch("index")) }
+        expected = (0...input_count).to_a
+        raise ProtocolError, "OpenAI returned invalid embedding indices" unless ordered.map { |item| Integer(item.fetch("index")) } == expected
+
+        vectors = ordered.map { |item| item.fetch("embedding") }
+        if expected_dimensions && vectors.any? { |vector| !vector.is_a?(Array) || vector.length != expected_dimensions }
+          raise ProtocolError, "OpenAI returned embeddings with unexpected dimensions"
+        end
+
+        usage = payload.fetch("usage", {})
+        Embeddings::Response.new(
+          vectors:,
+          usage: Usage.new(input_tokens: usage["prompt_tokens"] || usage["input_tokens"]),
+          metadata: {model: payload["model"] || model}
+        )
+      rescue JSON::ParserError, KeyError, ArgumentError, TypeError
+        raise ProtocolError, "OpenAI returned an invalid embedding response"
       end
     end
   end

data/lib/little_ghost/run.rb

@@ -112,7 +112,6 @@ module LittleGhost
       @closed = false
       @started = false
       @mutex = Mutex.new
-      @event_mutex = Mutex.new
       @subagent_instrumentation_mutex = Mutex.new
       @subagent_instrumentation = {}
       @assembly_step_instrumentation_mutex = Mutex.new
@@ -146,9 +145,10 @@ module LittleGhost
       return enum_for(__method__) unless block_given?
 
       begin_execution!
-      @emitter = lambda do |event|
-        @event_mutex.synchronize { yield_event(event) { |value| yield value } }
+      dispatcher = Support::SerializedDispatcher.new do |event|
+        yield_event(event) { |value| yield value }
       end
+      @emitter = dispatcher.method(:call)
       Instrumentation.with_context(correlation_attributes.except(:operation_id)) do
         execute { |event| @emitter.call(event) }
       end
@@ -175,8 +175,8 @@ module LittleGhost
 
     # Adds an interjection to the active entrypoint and waits for its response.
     #
-    # Raises LittleGhost::AgentInterjectionError before the entrypoint is ready,
-    # after it finishes, or when the entrypoint does not support interjections.
+    # Raises LittleGhost::AgentInterjectionError before the entrypoint is ready
+    # or after it finishes.
     def interject(
       message,
       interjection_id: nil,
@@ -211,10 +211,6 @@ module LittleGhost
         @active_interjections += 1
         @entrypoint
       end
-      unless entrypoint.respond_to?(:interject)
-        raise AgentInterjectionError, "Run entrypoint does not support interjections"
-      end
-
       message, options = yield
       entrypoint.interject(message, **options)
     ensure
@@ -378,7 +374,7 @@ module LittleGhost
       emit(:trace_context, context: trace_context) { |event| yield event } unless trace_context.nil? || trace_context.empty?
       workspace&.open(run: self)
       sandbox&.open(run: self)
-      runtime.prepare_execution(self) if runtime.respond_to?(:prepare_execution)
+      runtime.prepare_execution(self)
       @session = runtime.open_session(self)
       agent = runtime.build_assembly(@execution_class, run: self)
       @interjection_mutex.synchronize do
@@ -560,17 +556,15 @@ module LittleGhost
     def workflow_run? = defined?(Workflow) && entrypoint_class <= Workflow
 
     def entrypoint_kind
-      return entrypoint_class.assembly_kind if entrypoint_class.respond_to?(:assembly_kind)
-
-      workflow_run? ? :workflow : :agent
+      entrypoint_class.assembly_kind
     end
 
     def entrypoint_name
       return entrypoint_class.name.to_s if workflow_run?
 
-      return @entrypoint.entrypoint_name if @entrypoint&.respond_to?(:entrypoint_name)
+      return @entrypoint.entrypoint_name if @entrypoint
 
-      entrypoint_class.respond_to?(:assembly_id) ? entrypoint_class.assembly_id : entrypoint_class.name.to_s
+      entrypoint_class.assembly_id
     end
 
     def instrument_subagent(data)

data/lib/little_ghost/run_context.rb

@@ -7,7 +7,8 @@ module LittleGhost
   #
   # Tools and workflows use it to share JSON-like state, check
   # cancellation and deadlines, checkpoint messages, and accumulate usage.
-  # Access to framework-managed fields is thread-safe.
+  # Framework-managed fields remain safe when calls overlap on threads or
+  # fibers.
   class RunContext
     # Mutable DataMap state supplied to this invocation. A top-level Run starts
     # with restored Session state merged with current Invocation context; child

data/lib/little_ghost/runtime/hooks/artifacts.rb

@@ -91,6 +91,7 @@ module LittleGhost
             automatic: automatic_descriptor,
             oversized:
           )
+          content = append_materialized_references(content, all_descriptors)
           Tool::ExecutionResult.new(
             value: result.value,
             content:,
@@ -229,6 +230,13 @@ module LittleGhost
           end.freeze
         end
 
+        def append_materialized_references(content, artifacts)
+          references = artifacts.filter_map { |artifact| artifact.reference if artifact.bytes }
+          return content if references.empty?
+
+          "#{content}\n\nWorkspace artifacts:\n#{references.map { |reference| "- #{reference}" }.join("\n")}"
+        end
+
         def oversized_artifact(result, tool_use:)
           data, media_type, extension = serialized_value(result.value)
           Artifact.new(

data/lib/little_ghost/runtime.rb

@@ -53,9 +53,14 @@ module LittleGhost
   # security boundary for untrusted work.
   #
   # Shared stores, resolvers, hooks, subscribers, providers, and resource
-  # factories may receive calls from several threads and must be thread-safe.
-  # One SessionStore instance serializes calls for the same Session. A store
-  # must provide its own coordination across processes.
+  # factories may receive concurrent calls. Calls can overlap on different
+  # threads, or fibers can take turns entering the same object on one thread.
+  # Extensions must protect shared mutable state without relying on thread
+  # identity. One SessionStore instance serializes calls for the same Session.
+  # A store must provide its own coordination across processes.
+  #
+  # See {Running in Production}[rdoc-ref:docs/guides/production.md] for
+  # choosing a concurrency backend and protecting shared extensions.
   #
   # Runtime has no shutdown operation. Runs close resources created for their
   # request. The application shuts down shared services and process-wide
@@ -87,6 +92,7 @@ module LittleGhost
     attr_reader :code_mode_configuration
     # Runtime hooks called around request and session preparation.
     attr_reader :runtime_hooks
+    attr_reader :task_runner # :nodoc:
 
     # Starts a runtime from +configuration+ or an existing settings snapshot.
     def initialize(configuration:, settings: nil)
@@ -105,6 +111,9 @@ module LittleGhost
           configuration.load_file!(root: bootstrap_root)
           @settings = configuration.settings(root: bootstrap_root)
         end
+        @task_runner = Support::TaskRunner.new(
+          backend: @settings.fetch(:concurrency_backend, :auto)
+        )
         report_startup(status: "starting")
         @startup_reported = true
         @root = canonical_application_root(@settings.fetch(:root))
@@ -127,6 +136,7 @@ module LittleGhost
         @invocation_class = @settings[:invocation] || Invocation
         @model_resolver = @settings.fetch(:model_resolver)
         @default_model = @settings.fetch(:default_model, "default").to_s
+        @model_operations = ModelOperations.new(model_resolver:)
 
         @startup_phase = "session_store"
         @session_store = build_session_store(@settings[:session_store])
@@ -174,6 +184,28 @@ module LittleGhost
       payload.is_a?(@invocation_class) ? payload : @invocation_class.new(payload)
     end
 
+    # :call-seq:
+    #   generate(model:, messages:, result_schema: nil, settings: {}, structured_result_repair_attempts: 1, cancellation_token: Support::CancellationToken.new, deadline: nil) -> RunResult
+    #
+    # Generates one response through this Runtime's model resolver.
+    #
+    # Returns a RunResult without creating a Run or invoking runtime hooks. See
+    # LittleGhost.generate for the operation contract.
+    def generate(**arguments)
+      @model_operations.generate(**arguments)
+    end
+
+    # :call-seq:
+    #   embed(model:, inputs:, settings: {}, limits: {}, cancellation_token: Support::CancellationToken.new, deadline: nil) -> Embeddings::Response
+    #
+    # Embeds text through this Runtime's model resolver.
+    #
+    # Returns an Embeddings::Response without creating a Run or invoking runtime
+    # hooks. See LittleGhost.embed for the operation contract.
+    def embed(**arguments)
+      @model_operations.embed(**arguments)
+    end
+
     # Creates a Run that owns any workspace and sandbox built for the request.
     #
     # +include_agent_events_by_default+ is trusted stream policy for the Run

data/lib/little_ghost/sandbox/process_runner.rb

@@ -68,7 +68,7 @@ module LittleGhost
       def terminate(pid)
         Process.kill("TERM", -pid)
         deadline = monotonic_time + TERMINATION_GRACE
-        Thread.pass while monotonic_time < deadline && process_group_alive?(pid)
+        sleep(POLL_INTERVAL) while monotonic_time < deadline && process_group_alive?(pid)
         Process.kill("KILL", -pid) if process_group_alive?(pid)
       rescue Errno::ESRCH, Errno::EPERM
         nil

data/lib/little_ghost/sandboxes/unrestricted.rb

@@ -174,7 +174,6 @@ module LittleGhost
           raise ToolError, "Command timed out" if monotonic_time >= deadline
 
           wait_thread.join(0.01)
-          Thread.pass
         end
       rescue
         terminate(wait_thread.pid)
@@ -187,7 +186,7 @@ module LittleGhost
         while monotonic_time < deadline
           return unless process_group_alive?(pid)
 
-          Thread.pass
+          sleep(0.01)
         end
 
         Process.kill("KILL", -pid)

data/lib/little_ghost/session_stores/filesystem.rb

@@ -21,16 +21,24 @@ module LittleGhost
     # pass it directly when opening a Session. Calls for the same session wait
     # for one writer, including when separate Ruby processes share the root.
     #
-    # **Warning:** The root contains readable session data and is not encrypted.
-    # Its complete path must be application-controlled: anyone able to read it
-    # can read session data, and anyone able to replace it can alter sessions.
+    # >>>
+    #   <b>Safety note:</b> The root contains readable session data and is not
+    #   encrypted. Its complete path must be application-controlled: anyone able
+    #   to read it can read session data, and anyone able to replace it can alter
+    #   sessions.
     #
     # Session data is stored as ordinary JSON with canonical String keys. A
-    # value outside that boundary raises ProtocolError without replacing the
-    # previous snapshot. Shared roots require filesystem support for file
-    # locking and atomic rename.
+    # value that cannot be represented that way raises ProtocolError without
+    # replacing the previous snapshot. Shared roots require filesystem support for file
+    # locking and atomic rename. Waiting for another process does not pause other
+    # scheduled fibers. In a scheduled fiber, file transactions use
+    # LittleGhost's shared thread pool. Set Configuration#blocking_pool_capacity
+    # during process startup if measurements show calls waiting for its two
+    # default workers. Store calls do not accept cancellation or deadlines, so
+    # a cross-process lock wait continues until the other process releases it.
     class Filesystem < SessionStore
       FORMAT_VERSION = 1 # :nodoc:
+      LOCK_RETRY_INTERVAL = 0.01 # :nodoc:
 
       # Creates a store rooted at +root+ and creates the directory when needed.
       #
@@ -62,9 +70,10 @@ module LittleGhost
       # Atomically appends sanitized +messages+ and returns the updated snapshot.
       #
       # +expected_count+ must match the stored history length. +state+ and
-      # +metadata+ must meet this store's JSON boundary. Raises ProtocolError
-      # when another writer changed the session or the snapshot cannot be read
-      # or written. Raises Error when +actor_id+ does not match the session.
+      # +metadata+ must contain values this store can represent as JSON. Raises
+      # ProtocolError when another writer changed the session or the snapshot
+      # cannot be read or written. Raises Error when +actor_id+ does not match
+      # the session.
       def append(id, messages:, state:, metadata:, expected_count:, actor_id: nil)
         messages = persistable_messages(messages)
         state = canonical_map(state)
@@ -135,10 +144,17 @@ module LittleGhost
         path = lock_path(id)
         validate_entry!(path) if File.exist?(path) || File.symlink?(path)
         File.open(path, File::RDWR | File::CREAT, 0o600) do |lock|
-          lock.flock(File::LOCK_EX)
-          yield
-        ensure
-          lock.flock(File::LOCK_UN)
+          loop do
+            if lock.flock(File::LOCK_EX | File::LOCK_NB)
+              begin
+                accepted, value = Support::Executor.blocking.try_call { yield }
+                return value if accepted
+              ensure
+                lock.flock(File::LOCK_UN)
+              end
+            end
+            sleep(LOCK_RETRY_INTERVAL)
+          end
         end
       end