little_ghost 0.2.0 → 0.3.0

data/lib/little_ghost/run.rb

@@ -3,7 +3,7 @@
 require "securerandom"
 
 module LittleGhost
-  # Observe one top-level agent or workflow execution from start to finish.
+  # Observe one top-level assembly execution from start to finish.
   # A run records its response, outcome, usage, error, and owned resources.
   #
   #   run = CustomerSupportAgent.ask("Why is transfer 481 pending?")
@@ -12,11 +12,11 @@ module LittleGhost
   #   run.outcome    # => "completed"
   #   run.response   # => "Transfer 481 is waiting for the receiving bank."
   #
-  # The class-level ask helper[rdoc-ref:LittleGhost::Agent.ask] or standalone
-  # ask method[rdoc-ref:LittleGhost::Agent#ask] consumes the event stream and
+  # The class-level ask helper[rdoc-ref:LittleGhost::Assembly.ask] or standalone
+  # ask method[rdoc-ref:LittleGhost::Assembly#ask] consumes the event stream and
   # returns the Run. For a live interface, the class-level streaming
-  # helper[rdoc-ref:LittleGhost::Agent.stream_ask] or standalone streaming
-  # method[rdoc-ref:LittleGhost::Agent#stream_ask] yields StreamEvent objects
+  # helper[rdoc-ref:LittleGhost::Assembly.stream_ask] or standalone streaming
+  # method[rdoc-ref:LittleGhost::Assembly#stream_ask] yields StreamEvent objects
   # and returns the same run after enumeration. A run can execute only once.
   #
   # Completion, failure, deadline, and cancellation become the +completed+,
@@ -25,7 +25,7 @@ module LittleGhost
   # delivery, or instrumentation failures may still raise because the framework
   # cannot safely report a clean stop.
   #
-  # The run opens its workspace, sandbox, session, and entrypoint, then closes
+  # The run opens its workspace, sandbox, session, and assembly entrypoint, then closes
   # registered resources in reverse order. +register+ extends that lifecycle for
   # application resources. Interruption is available only while an agent
   # entrypoint is active and unambiguous.
@@ -38,11 +38,17 @@ module LittleGhost
       :outcome, :response, :error, :session, :usage, :workspace, :sandbox
 
     # Creates a dormant run for +invocation+.
-    def initialize(invocation:, agent_class:, runtime:, entrypoint_class: agent_class,
+    def initialize(invocation:, runtime:, agent_class: nil, assembly_class: nil, entrypoint_class: nil,
+      execution_class: nil,
       cancellation_token: Support::CancellationToken.new, workspace: nil, sandbox: nil)
+      entrypoint_class ||= assembly_class || agent_class
+      raise ArgumentError, "entrypoint_class is required" unless entrypoint_class
+      execution_class ||= assembly_class || entrypoint_class
+
       @runtime = runtime
       @agent_class = agent_class
       @entrypoint_class = entrypoint_class
+      @execution_class = execution_class
       @invocation = invocation
       @cancellation_token = cancellation_token
       @workspace = workspace
@@ -55,11 +61,15 @@ module LittleGhost
       @event_mutex = Mutex.new
       @subagent_instrumentation_mutex = Mutex.new
       @subagent_instrumentation = {}
+      @assembly_step_instrumentation_mutex = Mutex.new
+      @assembly_step_instrumentation = {}
       @exclusive_tools_mutex = Mutex.new
       @once_mutex = Mutex.new
       @once_keys = {}
       @interruption_mutex = Mutex.new
+      @interruption_condition = ConditionVariable.new
       @interruption_state = :not_started
+      @active_interruptions = 0
       @entrypoint = nil
       @usage = Usage.new
     end
@@ -110,6 +120,21 @@ module LittleGhost
       cancellation_token: Support::CancellationToken.new,
       deadline: nil
     )
+      interrupt_response_with do
+        [
+          message,
+          {
+            interruption_id:,
+            batch_key:,
+            metadata:,
+            cancellation_token:,
+            deadline:
+          }
+        ]
+      end
+    end
+
+    def interrupt_response_with # :nodoc:
       entrypoint = @interruption_mutex.synchronize do
         case @interruption_state
         when :not_started, :starting
@@ -118,20 +143,22 @@ module LittleGhost
           raise AgentInterruptError, "Run has already finished"
         end
 
+        @active_interruptions += 1
         @entrypoint
       end
-      unless entrypoint.is_a?(Agent)
+      unless entrypoint.respond_to?(:interrupt_response)
         raise AgentInterruptError, "Run entrypoint does not support interruptions"
       end
 
-      entrypoint.interrupt_response(
-        message,
-        interruption_id:,
-        batch_key:,
-        metadata:,
-        cancellation_token:,
-        deadline:
-      )
+      message, options = yield
+      entrypoint.interrupt_response(message, **options)
+    ensure
+      if entrypoint
+        @interruption_mutex.synchronize do
+          @active_interruptions -= 1
+          @interruption_condition.broadcast
+        end
+      end
     end
 
     # Creates a RunContext with this run's cancellation token and deadline.
@@ -209,6 +236,10 @@ module LittleGhost
           outcome: cleanup_error ? :error : :cancelled,
           error_type: cleanup_error&.class&.name
         )
+        finish_remaining_assembly_step_instrumentation(
+          outcome: cleanup_error ? :error : :cancelled,
+          error_type: cleanup_error&.class&.name
+        )
       rescue => error
         errors << error
       end
@@ -229,7 +260,7 @@ module LittleGhost
         :run,
         parent: nil,
         **correlation_attributes,
-        entrypoint_kind: workflow_run? ? :workflow : :agent,
+        entrypoint_kind:,
         workflow_name: workflow_run? ? entrypoint_name : nil,
         trace_context: invocation[:parent_trace_context],
         trace_links: invocation[:trace_links],
@@ -241,17 +272,13 @@ module LittleGhost
       workspace&.open(run: self)
       sandbox&.open(run: self)
       @session = runtime.open_session(self)
-      agent = if entrypoint_class <= Agent
-        runtime.build_agent(entrypoint_class, run: self)
-      else
-        entrypoint_class.new(run: self, runtime:)
-      end
+      agent = runtime.build_assembly(@execution_class, run: self)
       @interruption_mutex.synchronize do
         @entrypoint = agent
       end
       register(agent)
       invoke = lambda do
-        history = session ? session.history(fallback: invocation.history) : invocation.history
+        history = session ? runtime.session_history(self, session, fallback: invocation.history) : invocation.history
         context = session ? session.state.merge(invocation.context) : invocation.context.dup
         options = {
           history:,
@@ -333,9 +360,10 @@ module LittleGhost
       ]
     ensure
       @interruption_mutex.synchronize do
+        @interruption_state = :terminal
+        @interruption_condition.wait(@interruption_mutex) while @active_interruptions.positive?
         @last_entrypoint = @entrypoint
         @entrypoint = nil
-        @interruption_state = :terminal
       end
       resource_cleanup_error = nil
       begin
@@ -402,25 +430,39 @@ module LittleGhost
     end
 
     def correlation_attributes
-      {
+      attributes = {
         operation_id:,
         run_id: invocation.run_id,
         invocation_id: invocation.invocation_id,
         session_id: invocation.session_id,
-        service_name: runtime.service_name,
-        agent_id: workflow_run? ? nil : entrypoint_name,
-        workflow_name: workflow_run? ? entrypoint_name : nil
-      }.compact
+        service_name: runtime.service_name
+      }
+      case entrypoint_kind
+      when :agent
+        attributes[:agent_id] = entrypoint_name
+      when :workflow
+        attributes[:workflow_name] = entrypoint_name
+      else
+        attributes[:assembly_id] = entrypoint_name
+        attributes[:assembly_kind] = entrypoint_kind
+      end
+      attributes
     end
 
-    def workflow_run? = entrypoint_class <= Workflow
+    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
+    end
 
     def entrypoint_name
       return entrypoint_class.name.to_s if workflow_run?
 
-      return @entrypoint.entrypoint_name if @entrypoint.is_a?(Agent)
+      return @entrypoint.entrypoint_name if @entrypoint&.respond_to?(:entrypoint_name)
 
-      entrypoint_class.agent_id
+      entrypoint_class.respond_to?(:assembly_id) ? entrypoint_class.assembly_id : entrypoint_class.name.to_s
     end
 
     def instrument_subagent(data)
@@ -485,7 +527,53 @@ module LittleGhost
         error_class ||= error if error.is_a?(String) && error.match?(/\A[A-Z]\w*(?:::[A-Z]\w*)*\z/)
         attributes = data.slice(:attempt, :delay, :error_code, :http_status, :partial_text)
         instrument(:model_retry, attributes.merge(error_class:).compact)
+      when :assembly_step_start
+        start_assembly_step_instrumentation(data)
+      when :assembly_step_stop
+        finish_assembly_step_instrumentation(data.fetch(:step_id), data.merge(outcome: :completed))
+      when :assembly_step_error
+        return unless data[:terminal]
+
+        finish_assembly_step_instrumentation(data.fetch(:step_id), data.merge(outcome: :error))
+      when :assembly_step_retry, :assembly_fork, :assembly_join, :assembly_transition, :assembly_handoff_loop
+        instrument(type, data.except(:usage))
+      end
+    end
+
+    def start_assembly_step_instrumentation(attributes)
+      step_id = attributes.fetch(:step_id)
+      handle = Instrumentation.start(
+        :assembly_step,
+        parent: attributes[:parent_operation_id] || operation_id,
+        operation_id: step_id,
+        detached: true,
+        assembly_id: attributes[:assembly_id],
+        assembly_kind: attributes[:assembly_kind],
+        participant: attributes[:participant],
+        branch_id: attributes[:branch_id]
+      )
+      @assembly_step_instrumentation_mutex.synchronize { @assembly_step_instrumentation[step_id] = handle }
+    end
+
+    def finish_assembly_step_instrumentation(step_id, attributes)
+      handle = @assembly_step_instrumentation_mutex.synchronize do
+        @assembly_step_instrumentation.delete(step_id)
+      end
+      return unless handle
+
+      usage = attributes[:usage]
+      handle.finish(
+        outcome: attributes[:outcome],
+        error_type: attributes[:error_type],
+        **(usage ? usage_attributes(usage) : {})
+      )
+    end
+
+    def finish_remaining_assembly_step_instrumentation(outcome:, error_type: nil)
+      handles = @assembly_step_instrumentation_mutex.synchronize do
+        @assembly_step_instrumentation.values.tap { @assembly_step_instrumentation.clear }
       end
+      handles.reverse_each { |handle| handle.finish(outcome:, error_type:) }
     end
 
     def start_subagent_instrumentation(attributes)

data/lib/little_ghost/run_result.rb

@@ -4,16 +4,16 @@ module LittleGhost
   # Associates a validated structured value with its declared schema name.
   StructuredResult = Data.define(:schema_name, :value) # :nodoc:
 
-  # RunResult gives callers one final view of an agent or workflow invocation.
-  # It includes the response, usage, updated conversation, state, and any
-  # validated structured value.
+  # RunResult gives callers one final view of an assembly invocation.
+  # It includes the response, usage, updated conversation, state, coordination
+  # steps, and any validated structured value.
   #
   # Use #output when the caller should accept either structured or textual
   # agents. It returns the validated structured value when present and #text
   # otherwise.
-  RunResult = Data.define(:message, :stop_reason, :usage, :messages, :state, :structured_result) do # :nodoc:
-    def initialize(message:, stop_reason:, usage:, messages:, state:, structured_result: nil)
-      super
+  RunResult = Data.define(:message, :stop_reason, :usage, :messages, :state, :structured_result, :steps) do # :nodoc:
+    def initialize(message:, stop_reason:, usage:, messages:, state:, structured_result: nil, steps: [])
+      super(message:, stop_reason:, usage:, messages:, state:, structured_result:, steps: Array(steps).freeze)
     end
 
     # Reads the final message text, or an empty string when no message exists.
@@ -30,6 +30,9 @@ module LittleGhost
     def output
       structured? ? structured_result.value : text
     end
+
+    # Returns immutable coordination queries for this result.
+    def trajectory = Assembly::Trajectory.new(steps)
   end
 
   # Associates a validated structured value with its declared schema name.
@@ -56,9 +59,9 @@ module LittleGhost
     # The locally validated application value.
   end
 
-  # RunResult gives callers one final view of an agent or workflow invocation.
-  # It includes the response, usage, updated conversation, state, and any
-  # validated structured value.
+  # RunResult gives callers one final view of an Assembly invocation.
+  # It includes the response, usage, updated conversation, state, coordination
+  # steps, and any validated structured value.
   #
   # Use #output when the caller should accept either structured or textual
   # agents. It returns the validated structured value when present and #text
@@ -68,9 +71,9 @@ module LittleGhost
     # :singleton-method: new
     # :call-seq:
     #   new(message:, stop_reason:, usage:, messages:, state:,
-    #       structured_result: nil) -> RunResult
+    #       structured_result: nil, steps: []) -> RunResult
     #
-    # Creates the terminal value for one agent or workflow invocation.
+    # Creates the terminal value for one Assembly invocation.
 
     ##
     # :attr_reader: message
@@ -96,6 +99,10 @@ module LittleGhost
     # :attr_reader: structured_result
     # The validated StructuredResult, or +nil+ for a textual result.
 
+    ##
+    # :attr_reader: steps
+    # Immutable Assembly::Step records for composite invocations.
+
     ##
     # :method: text
     # Reads the final message text, or an empty string when no message exists.
@@ -107,5 +114,9 @@ module LittleGhost
     ##
     # :method: output
     # Uses the structured value when present and otherwise #text.
+
+    ##
+    # :method: trajectory
+    # Returns an Assembly::Trajectory for querying immutable coordination steps.
   end
 end

data/lib/little_ghost/runtime/hook.rb

@@ -2,8 +2,8 @@
 
 module LittleGhost
   class Runtime
-    # Hooks let applications prepare runs, transform interruptions, and map
-    # errors to caller-safe messages.
+    # Hooks let applications prepare runs, select session history, transform
+    # interruptions, and map errors to caller-safe messages.
     #
     # Hooks are instantiated once per Runtime in configuration order. Override
     # only the methods needed and return the supplied value when leaving it
@@ -23,6 +23,11 @@ module LittleGhost
       # Transforms an interruption payload before it reaches the agent.
       def prepare_interruption(_run, payload) = payload
 
+      # Returns the history to use for this run, or nil to defer to later hooks
+      # and the session default. +stored+ is empty when the session is new;
+      # +fallback+ contains messages supplied by the invocation.
+      def session_history(_run, stored:, fallback:) = nil
+
       # Returns a caller-safe error message, or nil to defer to later hooks and
       # the runtime default. Avoid exposing secrets or internal exception text.
       def error_message(_error, _run) = nil

data/lib/little_ghost/runtime.rb

@@ -4,7 +4,7 @@ require "json"
 require_relative "configuration"
 
 module LittleGhost
-  # Prepare the shared services that agents and workflows use across many runs.
+  # Prepare the shared services that assemblies use across many runs.
   # A runtime owns model resolution, loading, persistence, lookup paths, hooks,
   # and resource factories for one Ruby setup.
   #
@@ -91,8 +91,8 @@ module LittleGhost
         @prompt_paths = build_lookup_paths(:prompt_paths)
         @skill_paths = build_lookup_paths(:skill_paths)
 
-        @startup_phase = "agent_builder"
-        @agent_builder = AgentBuilder.new(
+        @startup_phase = "agent_factory"
+        @agent_factory = AgentFactory.new(
           runtime: self,
           prompt_paths: @prompt_paths,
           resolve_agent: method(:resolve_agent_class)
@@ -133,11 +133,19 @@ module LittleGhost
     # sandbox resources to it.
     def build_run(
       payload,
-      agent_class:,
-      entrypoint_class: agent_class,
+      agent_class: nil,
+      assembly_class: nil,
+      entrypoint_class: nil,
+      execution_class: nil,
+      cancellation_token: Support::CancellationToken.new,
       workspace: nil,
       sandbox: nil
     )
+      entrypoint_class ||= assembly_class || agent_class
+      raise ArgumentError, "entrypoint_class is required" unless entrypoint_class
+
+      execution_class ||= assembly_class || entrypoint_class
+      agent_class ||= entrypoint_class if entrypoint_class <= Agent
       owned_resources = []
       workspace ||= build_workspace.tap { |resource| owned_resources << resource }
       sandbox ||= build_sandbox(workspace:).tap { |resource| owned_resources << resource }
@@ -146,6 +154,8 @@ module LittleGhost
         runtime: self,
         agent_class:,
         entrypoint_class:,
+        execution_class:,
+        cancellation_token:,
         workspace:,
         sandbox:
       )
@@ -183,7 +193,41 @@ module LittleGhost
       tools: [],
       agent_path: Subagents::AgentPath::ROOT
     )
-      @agent_builder.build(agent_class_or_name, run:, model:, tools:, agent_path:)
+      agent_class_or_name = agent_class_or_name.definition if agent_class_or_name.is_a?(AgentBuilder)
+      if agent_class_or_name.is_a?(AssemblyDefinition)
+        unless agent_class_or_name.kind == :agent
+          raise ConfigurationError, "agent definition must have kind :agent"
+        end
+        agent_class_or_name = agent_class_or_name.implementation
+      end
+      @agent_factory.build(agent_class_or_name, run:, model:, tools:, agent_path:)
+    end
+
+    # Builds an Agent through AgentFactory or constructs another Assembly for +run+.
+    def build_assembly(assembly_class_or_name, run:, **options) # :nodoc:
+      if assembly_class_or_name.is_a?(AssemblyBuilder)
+        assembly_class_or_name = assembly_class_or_name.definition
+      end
+      if assembly_class_or_name.is_a?(Class) && assembly_class_or_name <= Assembly
+        assembly_class_or_name = assembly_class_or_name.definition
+      end
+      if assembly_class_or_name.is_a?(AssemblyDefinition)
+        return build_agent(assembly_class_or_name, run:, **options) if assembly_class_or_name.kind == :agent
+        raise ArgumentError, "composite assembly definitions do not accept agent build options" unless options.empty?
+
+        return assembly_class_or_name.implementation.new(run:, runtime: self)
+      end
+      if !assembly_class_or_name.is_a?(Class) || assembly_class_or_name <= Agent
+        return build_agent(assembly_class_or_name, run:, **options)
+      end
+      unless assembly_class_or_name <= Assembly
+        raise ConfigurationError, "assembly must inherit from LittleGhost::Assembly"
+      end
+      unless options.empty?
+        raise ArgumentError, "composite assemblies do not accept agent build options"
+      end
+
+      assembly_class_or_name.new(run:, runtime: self)
     end
 
     # The low-cardinality service name attached to runtime telemetry.
@@ -205,6 +249,16 @@ module LittleGhost
       )
     end
 
+    def session_history(run, session, fallback:) # :nodoc:
+      stored = session.history
+      runtime_hooks.each do |hook|
+        history = hook.session_history(run, stored:, fallback:)
+        return normalize_history(history) unless history.nil?
+      end
+
+      session.history(fallback:)
+    end
+
     def prepare_run(run) # :nodoc:
       runtime_hooks.each { |hook| hook.prepare_run(run) }
       run
@@ -282,6 +336,10 @@ module LittleGhost
       Array(hook_classes).map(&:new)
     end
 
+    def normalize_history(history)
+      Array(history).map { |message| Message.coerce(message) }.freeze
+    end
+
     def build_session_store(definition)
       return SessionStores::Memory.new unless definition
 

data/lib/little_ghost/sandbox.rb

@@ -20,7 +20,7 @@ module LittleGhost
   #       result = @container.run(
   #         command, timeout:, cancellation: context&.cancellation_token
   #       )
-  #       Execution.new(**result)
+  #       LittleGhost::Sandbox::Execution.new(**result)
   #     end
   #   end
   #

data/lib/little_ghost/support/executor.rb

@@ -31,6 +31,8 @@ module LittleGhost
         items.each_index { |index| queue << index }
         results = Array.new(items.length)
         errors = Array.new(items.length)
+        error_mutex = Mutex.new
+        first_worker_error = nil
         worker_count = [@max_concurrency, items.length].min
         execution_state = ExecutionState.capture
 
@@ -49,6 +51,8 @@ module LittleGhost
                   results[index] = block.call(items[index])
                 rescue => error
                   errors[index] = error
+                  error_mutex.synchronize { first_worker_error ||= error }
+                  cancellation_token.cancel
                 ensure
                   completions << index
                 end
@@ -56,16 +60,24 @@ module LittleGhost
             end
           end
         end
+        callback_error = nil
         begin
           items.length.times do
             index = completions.pop
-            on_result.call(index, results[index]) if on_result && !errors[index]
+            begin
+              on_result.call(index, results[index]) if on_result && !errors[index]
+            rescue => error
+              callback_error = error
+              cancellation_token.cancel
+              break
+            end
           end
         ensure
           workers.each(&:join)
         end
 
-        first_error = errors.compact.find { |error| error.is_a?(CleanupError) } || errors.compact.first
+        raise callback_error if callback_error
+        first_error = errors.compact.find { |error| error.is_a?(CleanupError) } || first_worker_error
         raise first_error if first_error
 
         results

data/lib/little_ghost/support/loader.rb

@@ -5,7 +5,7 @@ require "monitor"
 
 module LittleGhost
   module Support
-    # Loader finds agents and tools from a conventional application layout. Ruby
+    # Loader finds agents, assemblies, and tools from a conventional application layout. Ruby
     # files map to constants by path, so applications can add extension classes
     # without maintaining a manual require list.
     #
@@ -16,7 +16,7 @@ module LittleGhost
     # checked for symbolic-link escapes. Application load roots are trusted code,
     # not a sandbox for untrusted files.
     class Loader
-      DEFAULT_DIRECTORIES = %w[app/agents app/tools].freeze # :nodoc:
+      DEFAULT_DIRECTORIES = %w[app/agents app/assemblies app/tools].freeze # :nodoc:
       PROCESS_LOCK = Monitor.new # :nodoc:
 
       # Application root and configured relative load directories.

data/lib/little_ghost/support.rb

@@ -9,17 +9,29 @@ module LittleGhost
 
     # Recursively duplicates hashes, arrays, and strings while preserving other
     # values. Cyclic containers are not supported.
-    def deep_dup(value)
+    def deep_dup(value, ancestors = {})
+      if value.is_a?(Hash) || value.is_a?(Array) || value.is_a?(Data)
+        identity = value.object_id
+        raise ArgumentError, "cyclic values cannot be duplicated" if ancestors.key?(identity)
+
+        ancestors[identity] = true
+      end
       case value
       when Hash
-        value.each_with_object({}) { |(key, child), copy| copy[deep_dup(key)] = deep_dup(child) }
+        value.each_with_object({}) do |(key, child), copy|
+          copy[deep_dup(key, ancestors)] = deep_dup(child, ancestors)
+        end
       when Array
-        value.map { |child| deep_dup(child) }
+        value.map { |child| deep_dup(child, ancestors) }
       when String
         value.dup
+      when Data
+        value.class.new(**value.to_h.transform_values { |child| deep_dup(child, ancestors) })
       else
         value
       end
+    ensure
+      ancestors.delete(identity) if identity
     end
   end
 end