little_ghost 0.2.1 → 0.4.0

data/lib/little_ghost/message.rb

@@ -21,8 +21,8 @@ module LittleGhost
     attr_reader :role, :content, :metadata
 
     # Creates a frozen message with a supported +role+, normalized +content+, and
-    # application-defined +metadata+. The content Array and metadata Hash are
-    # frozen, but nested caller-owned values are retained.
+    # application-defined +metadata+. Metadata becomes a frozen DataMap, so
+    # String and Symbol keys address the same JSON-compatible value.
     def initialize(role:, content:, metadata: {})
       @role = role.to_sym
       raise ArgumentError, "Unsupported message role: #{role.inspect}" unless ROLES.include?(@role)
@@ -35,7 +35,7 @@ module LittleGhost
         [content]
       end
       @content = blocks.map { |block| Content.normalize(block) }.freeze
-      @metadata = metadata.freeze
+      @metadata = DataMap.new(metadata).freeze
       freeze
     end
 
@@ -64,7 +64,7 @@ module LittleGhost
 
     # Produces the JSON-safe message representation.
     def to_h
-      {"role" => role.to_s, "content" => content.map(&:to_h), "metadata" => metadata}
+      {"role" => role.to_s, "content" => content.map(&:to_h), "metadata" => metadata.to_h}
     end
 
     # Encodes #to_h as JSON, forwarding generator +arguments+.

data/lib/little_ghost/model_resolver.rb

@@ -30,7 +30,7 @@ module LittleGhost
       @providers = providers
       @connections = providers&.connections || {}
       @profiles = normalize_profiles(profiles || {})
-      @default_model = default_model&.to_s || "default"
+      @default_model = (default_model&.to_s || "default").dup.freeze
       @provider_registry = provider_adapters.empty? ? provider_registry : ProviderRegistry.new(adapters: provider_adapters)
       @credential_resolver = credential_resolver
       configure_default_providers unless providers
@@ -254,7 +254,7 @@ module LittleGhost
 
         parent = profile["inherits"] || profile[:inherits]
         validate_role_name!(parent.to_s) if parent
-        [role, profile.to_h]
+        [role, immutable_selection_value(profile.to_h)]
       end
     end
 

data/lib/little_ghost/prompt_resolver.rb

@@ -71,6 +71,8 @@ module LittleGhost
   #
   # Every configured root is trusted Ruby code because ERB executes inside the
   # current process. Keep roots application-controlled and non-user-writable.
+  # See the {Prompts as Views guide}[rdoc-ref:docs/guides/prompt_views.md] for the
+  # conventional Agent workflow.
   class PromptResolver
     DEFAULT_MAX_DEPTH = 20 # :nodoc:
 

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,37 +12,81 @@ 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
-  # 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
-  # and returns the same run after enumeration. A run can execute only once.
+  # The class-level ask helper[rdoc-ref:LittleGhost::Assembly.ask] and standalone
+  # ask method[rdoc-ref:LittleGhost::Assembly#ask] return the Run after work
+  # finishes. For a live interface, use the class-level streaming
+  # helper[rdoc-ref:LittleGhost::Assembly.stream_ask] or standalone streaming
+  # method[rdoc-ref:LittleGhost::Assembly#stream_ask]. The stream yields
+  # StreamEvent objects, and enumeration returns the same Run with its final
+  # outcome and response. A Run executes only once.
+  #
+  #   stream = CustomerSupportAgent.stream_ask("Where is transfer 481?")
+  #   run = stream.each do |event|
+  #     publish(event) if event.type == :text_delta
+  #   end
+  #
+  #   run.completed? # => true
+  #   run.response
   #
   # Completion, failure, deadline, and cancellation become the +completed+,
   # +failed+, +partial+, and +cancelled+ outcomes. Ordinary execution failures
-  # are available through +error+ and the terminal stream event; cleanup, event
-  # delivery, or instrumentation failures may still raise because the framework
-  # cannot safely report a clean stop.
+  # are available through +error+ and the terminal stream event. Failures while
+  # closing resources, delivering events, or reporting instrumentation may
+  # still raise because LittleGhost cannot report a reliable ending.
   #
-  # The run opens its workspace, sandbox, session, and 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.
+  # Tool validation and ToolError failures return safe Tool results to the model,
+  # which may recover and complete the Run. Input, configuration, or resource
+  # construction can raise before a Run exists. Once execution begins, terminal
+  # events are +run_stop+, +run_error+, +run_partial+, and +run_cancel+.
+  #
+  # The Run opens its workspace, sandbox, Session, and Assembly entrypoint, then
+  # closes registered resources in reverse order. +register+ adds application
+  # resources to that lifecycle. Interjection is available only while one Agent
+  # entrypoint is active.
   class Run
     include Enumerable
 
-    # Runtime and declarations used to execute the run; its request, cancellation
-    # token, resources, terminal outcome, response, result, usage, and error.
-    attr_reader :runtime, :agent_class, :entrypoint_class, :invocation, :cancellation_token, :result, :operation_id,
-      :outcome, :response, :error, :session, :usage, :workspace, :sandbox
+    # Runtime that built and executes this Run.
+    attr_reader :runtime
+    # Agent class used for compatibility when the entrypoint is an Agent.
+    attr_reader :agent_class
+    # Public Agent, Workflow, Swarm, or Graph class selected by the caller.
+    attr_reader :entrypoint_class
+    # Normalized request carried by this Run.
+    attr_reader :invocation
+    # Token that cooperatively stops this Run and its children.
+    attr_reader :cancellation_token
+    # Final RunResult, when the Assembly produced one.
+    attr_reader :result
+    # Unique identifier for this top-level operation.
+    attr_reader :operation_id
+    # Terminal String: +completed+, +failed+, +partial+, or +cancelled+.
+    attr_reader :outcome
+    # Caller-facing final text, or the partial text preserved at a deadline.
+    attr_reader :response
+    # Exception that caused a failed, partial, or cancelled outcome.
+    attr_reader :error
+    # Session opened for this invocation, when persistence is configured.
+    attr_reader :session
+    # Normalized Usage accumulated by the Run.
+    attr_reader :usage
+    # Request-scoped workspace owned or supplied by the Run.
+    attr_reader :workspace
+    # Request-scoped sandbox owned or supplied by the Run.
+    attr_reader :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 +99,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_state = :not_started
+      @interjection_mutex = Mutex.new
+      @interjection_condition = ConditionVariable.new
+      @interjection_state = :not_started
+      @active_interjections = 0
       @entrypoint = nil
       @usage = Usage.new
     end
@@ -98,40 +146,57 @@ module LittleGhost
     # True when cancellation stopped the run without a response.
     def cancelled? = outcome == "cancelled"
 
-    # Adds an interruption to the active entrypoint and waits for its response.
+    # Adds an interjection to the active entrypoint and waits for its response.
     #
-    # Raises LittleGhost::AgentInterruptError before the entrypoint is ready,
-    # after it finishes, or when the entrypoint does not support interruptions.
-    def interrupt_response(
+    # Raises LittleGhost::AgentInterjectionError before the entrypoint is ready,
+    # after it finishes, or when the entrypoint does not support interjections.
+    def interject(
       message,
-      interruption_id: nil,
+      interjection_id: nil,
       batch_key: nil,
       metadata: {},
       cancellation_token: Support::CancellationToken.new,
       deadline: nil
     )
-      entrypoint = @interruption_mutex.synchronize do
-        case @interruption_state
+      interject_with do
+        [
+          message,
+          {
+            interjection_id:,
+            batch_key:,
+            metadata:,
+            cancellation_token:,
+            deadline:
+          }
+        ]
+      end
+    end
+
+    def interject_with # :nodoc:
+      entrypoint = @interjection_mutex.synchronize do
+        case @interjection_state
         when :not_started, :starting
-          raise AgentInterruptError, "Run entrypoint is not ready for interruptions"
+          raise AgentInterjectionError, "Run entrypoint is not ready for interjections"
         when :terminal
-          raise AgentInterruptError, "Run has already finished"
+          raise AgentInterjectionError, "Run has already finished"
         end
 
+        @active_interjections += 1
         @entrypoint
       end
-      unless entrypoint.is_a?(Agent)
-        raise AgentInterruptError, "Run entrypoint does not support interruptions"
+      unless entrypoint.respond_to?(:interject)
+        raise AgentInterjectionError, "Run entrypoint does not support interjections"
       end
 
-      entrypoint.interrupt_response(
-        message,
-        interruption_id:,
-        batch_key:,
-        metadata:,
-        cancellation_token:,
-        deadline:
-      )
+      message, options = yield
+      entrypoint.interject(message, **options)
+    ensure
+      if entrypoint
+        @interjection_mutex.synchronize do
+          @active_interjections -= 1
+          @interjection_condition.broadcast
+        end
+      end
     end
 
     # Creates a RunContext with this run's cancellation token and deadline.
@@ -183,8 +248,8 @@ module LittleGhost
       end
     end
 
-    def prepare_interruption(payload) # :nodoc:
-      runtime.prepare_interruption(self, payload)
+    def prepare_interjection(payload) # :nodoc:
+      runtime.prepare_interjection(self, payload)
     end
 
     # Closes registered resources in reverse order.
@@ -209,6 +274,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 +298,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 +310,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
-      @interruption_mutex.synchronize do
+      agent = runtime.build_assembly(@execution_class, run: self)
+      @interjection_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:,
@@ -267,11 +332,11 @@ module LittleGhost
           end
         }
         if agent.is_a?(Agent)
-          options[:interrupt_ready] = lambda do
-            @interruption_mutex.synchronize { @interruption_state = :active }
+          options[:interject_ready] = lambda do
+            @interjection_mutex.synchronize { @interjection_state = :active }
           end
         else
-          @interruption_mutex.synchronize { @interruption_state = :active }
+          @interjection_mutex.synchronize { @interjection_state = :active }
         end
 
         agent.stream(invocation.message, **options).each do |event|
@@ -332,10 +397,11 @@ module LittleGhost
         }
       ]
     ensure
-      @interruption_mutex.synchronize do
+      @interjection_mutex.synchronize do
+        @interjection_state = :terminal
+        @interjection_condition.wait(@interjection_mutex) while @active_interjections.positive?
         @last_entrypoint = @entrypoint
         @entrypoint = nil
-        @interruption_state = :terminal
       end
       resource_cleanup_error = nil
       begin
@@ -402,25 +468,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 +565,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)
@@ -543,7 +669,7 @@ module LittleGhost
         raise Error, "run has already started" if @started
         @started = true
       end
-      @interruption_mutex.synchronize { @interruption_state = :starting }
+      @interjection_mutex.synchronize { @interjection_state = :starting }
     end
 
     def close_callback(resource)

data/lib/little_ghost/run_context.rb

@@ -9,12 +9,25 @@ module LittleGhost
   # cancellation and deadlines, checkpoint messages, and accumulate usage.
   # Access to framework-managed fields is thread-safe.
   class RunContext
-    # Shared state, cancellation, deadline, metadata, operation identity, and
-    # durable conversation identity for the current work.
-    attr_reader :state, :cancellation_token, :deadline, :metadata,
-      :agent_operation_id, :conversation_id
-
-    # Creates a context with optional checkpoint and interruption state.
+    # Mutable DataMap state supplied to this invocation. A top-level Run starts
+    # with restored Session state merged with current Invocation context; child
+    # Assemblies may receive copied, mapped, or empty state. Application code must
+    # synchronize mutations when parallel Tools share this map, or use exclusive
+    # Tools. String and Symbol keys address the same value; persisted snapshots
+    # use canonical String keys.
+    attr_reader :state
+    # Token used to cooperatively stop the current work.
+    attr_reader :cancellation_token
+    # Wall-clock deadline for the current work, when present.
+    attr_reader :deadline
+    # Framework metadata attached to this context.
+    attr_reader :metadata
+    # Active Agent operation identifier, after the context is bound.
+    attr_reader :agent_operation_id
+    # Durable subagent conversation identifier, when present.
+    attr_reader :conversation_id
+
+    # Creates a context with optional checkpoint and interjection state.
     def initialize(
       state: {},
       cancellation_token: Support::CancellationToken.new,
@@ -22,15 +35,15 @@ module LittleGhost
       metadata: {},
       checkpoint: nil,
       conversation_id: nil,
-      interruption_metadata: nil,
-      interruption_ids: []
+      interjection_metadata: nil,
+      interjection_ids: []
     )
       if conversation_id
         conversation_id = String(conversation_id)
         raise ArgumentError, "conversation_id cannot be empty" if conversation_id.empty?
         conversation_id = conversation_id.dup.freeze
       end
-      @state = state
+      @state = DataMap.new(state)
       @cancellation_token = cancellation_token
       @deadline = deadline
       @metadata = metadata.freeze
@@ -42,9 +55,9 @@ module LittleGhost
       @structured_result_mutex = Mutex.new
       @agent_operation_id = nil
       @agent_operation_id_mutex = Mutex.new
-      @interruption_mutex = Mutex.new
-      @interruption_metadata = interruption_metadata&.to_h
-      @interruption_ids = Array(interruption_ids).map { |id| String(id).dup.freeze }.freeze
+      @interjection_mutex = Mutex.new
+      @interjection_metadata = interjection_metadata&.to_h
+      @interjection_ids = Array(interjection_ids).map { |id| String(id).dup.freeze }.freeze
     end
 
     # Raises LittleGhost::CancelledError or LittleGhost::DeadlineExceededError
@@ -99,20 +112,20 @@ module LittleGhost
       @structured_result_mutex.synchronize { @structured_result }
     end
 
-    def interruption_metadata # :nodoc:
-      @interruption_mutex.synchronize { @interruption_metadata }
+    def interjection_metadata # :nodoc:
+      @interjection_mutex.synchronize { @interjection_metadata }
     end
 
-    def interruption_ids # :nodoc:
-      @interruption_mutex.synchronize { @interruption_ids }
+    def interjection_ids # :nodoc:
+      @interjection_mutex.synchronize { @interjection_ids }
     end
 
-    def activate_interruption(metadata:, ids:) # :nodoc:
+    def activate_interjection(metadata:, ids:) # :nodoc:
       value = metadata&.to_h
       values = Array(ids).map { |id| String(id).dup.freeze }.freeze
-      @interruption_mutex.synchronize do
-        @interruption_metadata = value
-        @interruption_ids = values
+      @interjection_mutex.synchronize do
+        @interjection_metadata = value
+        @interjection_ids = values
       end
     end
 

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
+    # interjections, 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
@@ -20,8 +20,13 @@ module LittleGhost
       # lifecycle and close in reverse order.
       def prepare_run(run) = run
 
-      # Transforms an interruption payload before it reaches the agent.
-      def prepare_interruption(_run, payload) = payload
+      # Transforms an interjection payload before it reaches the agent.
+      def prepare_interjection(_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.