little_ghost 0.3.0 → 0.4.0

data/lib/little_ghost/{agent_interruptions.rb → agent_interjections.rb}

@@ -3,16 +3,16 @@
 require "securerandom"
 
 module LittleGhost
-  class AgentInterruptions # :nodoc: all
+  class AgentInterjections # :nodoc: all
     MAX_BATCH_SIZE = 100
-    MAX_INTERRUPTION_COUNT = 1_000
+    MAX_INTERJECTION_COUNT = 1_000
 
-    Response = Data.define(:text, :tool_calls, :interruption_ids, :batch_key) do
-      def initialize(text:, tool_calls:, interruption_ids: [], batch_key: nil)
+    Result = Data.define(:text, :tool_calls, :interjection_ids, :batch_key) do
+      def initialize(text:, tool_calls:, interjection_ids: [], batch_key: nil)
         super(
           text: String(text),
           tool_calls: !!tool_calls,
-          interruption_ids: Array(interruption_ids).map { |id| String(id).dup.freeze }.freeze,
+          interjection_ids: Array(interjection_ids).map { |id| String(id).dup.freeze }.freeze,
           batch_key: batch_key.nil? ? nil : String(batch_key).dup.freeze
         )
       end
@@ -21,7 +21,7 @@ module LittleGhost
     end
 
     Batch = Data.define(:tickets) do
-      def interruption_ids = tickets.map(&:id)
+      def interjection_ids = tickets.map(&:id)
       def batch_key = tickets.first&.batch_key
       def metadata = tickets.last&.metadata
     end
@@ -99,7 +99,7 @@ module LittleGhost
 
     def enqueue(message, id: SecureRandom.uuid, batch_key: nil, metadata: {})
       id = String(id)
-      raise ArgumentError, "interruption_id cannot be empty" if id.empty?
+      raise ArgumentError, "interjection_id cannot be empty" if id.empty?
 
       batch_key = String(batch_key) unless batch_key.nil?
       metadata = metadata.to_h
@@ -111,14 +111,14 @@ module LittleGhost
           unless existing.message.to_h == message.to_h &&
               existing.batch_key == batch_key &&
               existing.metadata == metadata
-            raise ArgumentError, "interruption_id has already been used with different input"
+            raise ArgumentError, "interjection_id has already been used with different input"
           end
 
           @waiters[existing] += 1
           return existing
         end
-        if @tickets_by_id.length >= MAX_INTERRUPTION_COUNT
-          raise AgentInterruptError, "Agent interruption capacity reached"
+        if @tickets_by_id.length >= MAX_INTERJECTION_COUNT
+          raise AgentInterjectionError, "Agent interjection capacity reached"
         end
 
         ticket = Ticket.new(message, id: id.freeze, batch_key: batch_key&.freeze, metadata:)
@@ -128,7 +128,7 @@ module LittleGhost
         ticket
       end
     rescue TypeError, NoMethodError
-      raise ArgumentError, "interruption_id, batch_key, and metadata are invalid"
+      raise ArgumentError, "interjection_id, batch_key, and metadata are invalid"
     end
 
     def deliver
@@ -166,7 +166,7 @@ module LittleGhost
         return true if @closed_error
         return false if @delivered || !@queue.empty?
 
-        @closed_error = AgentInterruptError.new("Agent is not currently running")
+        @closed_error = AgentInterjectionError.new("Agent is not currently running")
         true
       end
     end

data/lib/little_ghost/assembly.rb

@@ -14,10 +14,28 @@ module LittleGhost
   #   agent_run.response
   #   graph_run.response
   #
+  # Named subclasses are the usual form. +to_builder+ creates a mutable dynamic
+  # definition seeded by the class, while +definition+ returns the immutable
+  # snapshot used for one execution. Composite results expose Assembly::Step
+  # records through RunResult#trajectory.
+  #
   # A standalone assembly owns a top-level Run. An assembly built by a Runtime
   # participates in the existing run and returns a RunResult. Applications
   # normally subclass Agent, Workflow, Swarm, or Graph rather than Assembly
-  # directly.
+  # directly. Standalone calls automatically reuse the active Configuration's
+  # shared Runtime while keeping each Run and its resources independent.
+  #
+  # == What each calling form returns
+  #
+  # [<tt>CustomerSupportAgent.ask(...)</tt>]
+  #   A named class creates and returns a top-level Run.
+  # [<tt>CustomerSupportAgent.new(runtime: runtime).ask(...)</tt>]
+  #   A standalone instance also creates and returns a top-level Run.
+  # [<tt>runtime.build_assembly(..., run: run).call(...)</tt>]
+  #   A participant already bound to a Run returns its child RunResult.
+  # [<tt>stream_ask(...).each { |event| ... }</tt>]
+  #   A standalone stream returns its top-level Run after enumeration. A
+  #   run-scoped stream ends with an +invocation_stop+ event carrying RunResult.
   class Assembly
     extend Support::ClassAttributes
 
@@ -26,11 +44,18 @@ module LittleGhost
 
     class << self
       # Executes +message+ through a fresh standalone assembly and returns its Run.
+      #
+      # +options+ become Invocation fields. Common values include +history+,
+      # +context+, +settings+, +metadata+, +session_id+, +actor_id+, and
+      # +deadline_at+.
       def ask(message, **options)
         definition.implementation.new.ask(message, **options)
       end
 
       # Lazily streams +message+ through a fresh standalone assembly.
+      #
+      # Enumeration yields StreamEvent objects and returns the terminal Run.
+      # The same Invocation fields accepted by .ask may be supplied as +options+.
       def stream_ask(message, **options)
         snapshot = definition
         stream = nil
@@ -111,12 +136,18 @@ module LittleGhost
       end
     end
 
-    # The owning run, runtime, and optional standalone resources.
-    attr_reader :run, :runtime, :workspace, :sandbox
+    # The owning Run, or +nil+ for a standalone entrypoint.
+    attr_reader :run
+    # Runtime used to resolve participants and build Runs.
+    attr_reader :runtime
+    # Workspace supplied to this Assembly, when present.
+    attr_reader :workspace
+    # Sandbox supplied to this Assembly, when present.
+    attr_reader :sandbox
 
     def initialize(run: nil, runtime: nil, workspace: nil, sandbox: nil, standalone: run.nil?) # :nodoc:
       @run = run
-      @runtime = runtime || run&.runtime || Runtime.new(configuration: LittleGhost.configuration)
+      @runtime = runtime || run&.runtime || LittleGhost.runtime
       @workspace = workspace || (run.workspace if run&.respond_to?(:workspace))
       @sandbox = sandbox || (run.sandbox if run&.respond_to?(:sandbox))
       @standalone = standalone
@@ -162,11 +193,18 @@ module LittleGhost
     end
 
     # Runs +message+ to completion.
+    #
+    # A standalone instance returns its owning Run. A run-scoped instance
+    # returns the child RunResult.
     def ask(message, **options)
       call(message, **options)
     end
 
     # Lazily streams +message+ through the standalone or run-scoped assembly.
+    #
+    # A standalone stream returns its terminal Run after enumeration. A
+    # run-scoped stream finishes with an +invocation_stop+ event containing its
+    # RunResult.
     def stream_ask(message, **options)
       if standalone?
         options[:deadline_at] = options.delete(:deadline) if options.key?(:deadline)
@@ -182,11 +220,12 @@ module LittleGhost
 
     # Exposes this assembly as a Tool instance.
     #
-    # By default each call has empty conversational history. Set
-    # <tt>preserve_context: true</tt> to retain history serially. Every call still
-    # receives the invoking Tool::Context application state; +preserve_context+
-    # does not suppress it. Tools inside the assembly remain responsible for
-    # authorizing privileged work from trusted context.
+    # By default, calls do not remember earlier conversation history. Set
+    # <tt>preserve_context: true</tt> to carry that history from one tool call to
+    # the next. This option does not control working state: every call receives
+    # the invoking Tool's current RunContext#state, which may include current
+    # request values or values restored from a Session. Nested tools must still
+    # authorize privileged work with current, application-established values.
     def as_tool(name: self.class.assembly_id, description: self.class.description, preserve_context: false)
       assembly = self
       description = "Delegate a task to #{name}." if description.to_s.empty?
@@ -218,8 +257,8 @@ module LittleGhost
             parent_operation_id: assembly.run&.operation_id
           }
           if target.is_a?(Agent)
-            options[:interruption_metadata] = context&.interruption_metadata
-            options[:interruption_ids] = context&.interruption_ids || []
+            options[:interjection_metadata] = context&.interjection_metadata
+            options[:interjection_ids] = context&.interjection_ids || []
           end
           result = target.call(input.fetch("input"), **options)
           if result.is_a?(Run)
@@ -247,24 +286,19 @@ module LittleGhost
       ))
     end
 
-    # Adds +message+ to the single active leaf Agent and returns its text reply.
-    def interrupt(message, **options)
-      interrupt_response(message, **options).text
-    end
-
-    # Adds an interruption to the single active leaf Agent.
-    def interrupt_response(message, **options)
+    # Adds an interjection to the single active leaf Agent.
+    def interject(message, **options)
       child = @assembly_mutex.synchronize do
         active = @active_assemblies.dup
         if active.empty?
-          raise AgentInterruptError, "Assembly is not currently running"
+          raise AgentInterjectionError, "Assembly is not currently running"
         end
         if active.length > 1
-          raise AgentInterruptError, "Assembly has multiple active participants; the interruption target is ambiguous"
+          raise AgentInterjectionError, "Assembly has multiple active participants; the interjection target is ambiguous"
         end
         active.first
       end
-      child.interrupt_response(message, **options)
+      child.interject(message, **options)
     end
 
     # Closes resources owned directly by this assembly.

data/lib/little_ghost/assembly_builder.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
 module LittleGhost
-  # An immutable, executable snapshot produced by an AssemblyBuilder.
-  AssemblyDefinition = Data.define(:kind, :assembly_id, :description, :implementation) do
+  AssemblyDefinition = Data.define(:kind, :assembly_id, :description, :implementation) do # :nodoc:
     def initialize(kind:, assembly_id:, description:, implementation:)
       super(
         kind: kind.to_sym,
@@ -13,6 +12,29 @@ module LittleGhost
     end
   end
 
+  # The immutable, executable snapshot produced by an AssemblyBuilder.
+  #
+  # Runtime and other builders accept a definition anywhere they accept an
+  # Assembly reference. +implementation+ is the sealed class instantiated for
+  # this snapshot.
+  class AssemblyDefinition < Data # :doc:
+    ##
+    # :attr_reader: kind
+    # The Assembly kind: +:agent+, +:workflow+, +:swarm+, or +:graph+.
+
+    ##
+    # :attr_reader: assembly_id
+    # The stable identifier captured by the snapshot.
+
+    ##
+    # :attr_reader: description
+    # The human-readable description captured by the snapshot.
+
+    ##
+    # :attr_reader: implementation
+    # The sealed Assembly subclass used to build executions.
+  end
+
   # Builds an Assembly when its participants or routes are discovered at runtime.
   #
   # Class definitions are the usual, easier-to-find way to declare behavior.
@@ -230,6 +252,12 @@ module LittleGhost
   end
 
   # Builds an Agent definition from declarations made at runtime.
+  #
+  #   agent = LittleGhost::AgentBuilder.new(id: "customer_support")
+  #   agent.model "openrouter:openai/gpt-5.6-luna"
+  #   agent.system_prompt "Answer customer questions clearly."
+  #   agent.ask("Where is my order?")
+  #
   # Supported Agent class-DSL calls are recorded and replayed into each
   # immutable snapshot.
   class AgentBuilder < AssemblyBuilder
@@ -308,6 +336,9 @@ module LittleGhost
   end
 
   # Builds a Workflow whose Ruby composition block is supplied at runtime.
+  # Use a named Workflow subclass's +to_builder+ when the class supplies the
+  # composition and runtime configuration supplies its identity or description.
+  # +perform+ supplies the underlying dynamic form for trusted application code.
   class WorkflowBuilder < AssemblyBuilder
     class << self
       # :nodoc:
@@ -344,6 +375,13 @@ module LittleGhost
   end
 
   # Builds a Swarm at runtime while keeping its members Agent-only.
+  #
+  #   swarm = LittleGhost::SwarmBuilder.new(id: "problem_solver")
+  #   swarm.member TriageAgent
+  #   swarm.member BillingAgent
+  #   swarm.start TriageAgent
+  #   swarm.handoff TriageAgent, to: BillingAgent
+  #   swarm.validate!
   class SwarmBuilder < AssemblyBuilder
     class << self
       # :nodoc:

data/lib/little_ghost/assembly_execution.rb

@@ -8,15 +8,13 @@ module LittleGhost
     MAX_STEP_EVENTS = 10_000 # :nodoc:
     MAX_STEP_EVENT_BYTES = 10 * 1024 * 1024 # :nodoc:
 
-    # One attempt to execute an assembly step.
-    Attempt = Data.define(:number, :status, :started_at, :finished_at, :usage, :error) do
+    Attempt = Data.define(:number, :status, :started_at, :finished_at, :usage, :error) do # :nodoc:
       def initialize(number:, status:, started_at:, finished_at:, usage: Usage.new, error: nil)
         super(number:, status: status.to_sym, started_at:, finished_at:, usage:, error: error&.to_s&.freeze)
       end
     end
 
-    # One logical child execution in a composite assembly.
-    Step = Data.define(
+    Step = Data.define( # :nodoc:
       :id, :parent_id, :predecessor_ids, :branch_id, :participant,
       :assembly_id, :assembly_kind, :status, :attempts, :usage, :output, :output_truncated
     ) do
@@ -39,6 +37,91 @@ module LittleGhost
       end
     end
 
+    # One bounded attempt to execute a child Assembly step.
+    #
+    # It records timing, normalized usage, terminal status, and a sanitized error
+    # description suitable for the public coordination trajectory.
+    class Attempt < Data # :doc:
+      ##
+      # :attr_reader: number
+      # The one-based attempt number.
+
+      ##
+      # :attr_reader: status
+      # The normalized terminal status for this attempt.
+
+      ##
+      # :attr_reader: started_at
+      # The wall-clock start time.
+
+      ##
+      # :attr_reader: finished_at
+      # The wall-clock finish time.
+
+      ##
+      # :attr_reader: usage
+      # The Usage recorded by this attempt.
+
+      ##
+      # :attr_reader: error
+      # A sanitized error description, or +nil+.
+    end
+
+    # One logical child execution in a composite Assembly result.
+    #
+    # Steps identify the participant, relationships to other steps, attempts,
+    # usage, and a bounded semantic output. Use RunResult#trajectory for queries
+    # over several steps.
+    class Step < Data # :doc:
+      ##
+      # :attr_reader: id
+      # The stable identifier for this step occurrence.
+
+      ##
+      # :attr_reader: parent_id
+      # The containing step identifier for nested coordination, or +nil+.
+
+      ##
+      # :attr_reader: predecessor_ids
+      # Step identifiers whose results led to this step.
+
+      ##
+      # :attr_reader: branch_id
+      # The parallel branch identifier, or +nil+.
+
+      ##
+      # :attr_reader: participant
+      # The participant name used by the parent Assembly.
+
+      ##
+      # :attr_reader: assembly_id
+      # The invoked Assembly's stable identifier.
+
+      ##
+      # :attr_reader: assembly_kind
+      # The invoked Assembly kind.
+
+      ##
+      # :attr_reader: status
+      # The logical step's terminal status.
+
+      ##
+      # :attr_reader: attempts
+      # Immutable Attempt values, including retries.
+
+      ##
+      # :attr_reader: usage
+      # Usage accumulated across the step's attempts.
+
+      ##
+      # :attr_reader: output
+      # The bounded semantic output retained for coordination inspection.
+
+      ##
+      # :attr_reader: output_truncated
+      # Indicates that +output+ exceeded the public result limit.
+    end
+
     # Immutable queries over the steps returned by one assembly invocation.
     class Trajectory
       include Enumerable