class LittleGhost::Run

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?")

run.completed? # => true
run.outcome    # => "completed"
run.response   # => "Transfer 481 is waiting for the receiving bank."

ask returns the Run after work finishes. stream_ask yields StreamEvent objects as work happens, then returns the same finished Run. A Run executes only once.

stream = CustomerSupportAgent.stream_ask("Where is transfer 481?")
run = stream.each do |event|
  next unless event.type == :agent_stream

  source = event.data.fetch(:source)
  next unless source.agent_path == "/root" && source.assembly_path.empty?

  progress = event.data.fetch(:event)
  publish(progress) if progress.type == :text_delta
end

run.completed? # => true
run.response

Outcomes

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. Failures while closing resources, delivering events, or reporting instrumentation may still raise because LittleGhost cannot report a reliable ending.

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.

Owned resources

The Run opens its workspace, sandbox, Session, and Assembly entrypoint, then closes registered resources in reverse order. register adds application resources to that cleanup sequence. Interjection is available only while one Agent entrypoint is active.

Source-tagged progress

Every Run observes all participating Agents, including a root Agent’s subagents and Agents nested in Workflow, Swarm, or Graph steps. Each :agent_stream event carries an AgentStreamSource in data[:source] and a copied, frozen Agent StreamEvent in data[:event]. An inner :invocation_start also includes the copied, frozen Message sent to that Agent in data[:input]. Event consumers cannot change the running work.

Agent progress appears only through these wrappers, not as duplicate raw events. Lifecycle events and terminal RunResults are separate. Selecting a child result or computing an assembly answer does not replay text deltas.

Parallel Agents may interleave, but the Run invokes the stream consumer serially. Wrappers can contain inputs, reasoning, Tool arguments and results, and private participant output. Applications must filter sources and fields before sending them to destinations that may see less than the complete Run. Set include_agent_events: false to omit all Agent progress; execution, lifecycle events, and final results remain unchanged.

Attributes

agent_class [R]

Agent class used for compatibility when the entrypoint is an Agent.

cancellation_token [R]

Token that cooperatively stops this Run and its children.

entrypoint_class [R]

Public Agent, Workflow, Swarm, or Graph class selected by the caller.

error [R]

Exception that caused a failed, partial, or cancelled outcome.

invocation [R]

Normalized request carried by this Run.

operation_id [R]

Unique identifier for this top-level operation.

outcome [R]

Terminal String: completed, failed, partial, or cancelled.

response [R]

Caller-facing final text, or the partial text preserved at a deadline.

result [R]

Final RunResult, when the Assembly produced one.

runtime [R]

Runtime that built and executes this Run.

sandbox [R]

Request-scoped sandbox owned or supplied by the Run.

session [R]

Session opened for this invocation, when persistence is configured.

usage [R]

Normalized Usage accumulated by the Run.

workspace [R]

Request-scoped workspace owned or supplied by the Run.

Public Class Methods

new (invocation:, runtime:, agent_class: nil, assembly_class: nil, entrypoint_class: nil, execution_class: nil, cancellation_token: Support::CancellationToken.new, workspace: nil, sandbox: nil, include_agent_events_by_default: true)

Source

# File lib/little_ghost/run.rb, line 105
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,
  include_agent_events_by_default: true)
  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
  @sandbox = sandbox
  @operation_id = SecureRandom.uuid
  @resources = []
  @shared_resources = {}
  @shared_resource_condition = ConditionVariable.new
  @closed = false
  @started = false
  @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 = {}
  @interjection_mutex = Mutex.new
  @interjection_condition = ConditionVariable.new
  @interjection_state = :not_started
  @active_interjections = 0
  @entrypoint = nil
  @usage = Usage.new
  include_agent_events = invocation[:include_agent_events]
  unless include_agent_events.nil? || include_agent_events == true || include_agent_events == false
    raise InvocationError, "include_agent_events must be true or false"
  end
  @include_agent_events = include_agent_events.nil? ? include_agent_events_by_default : include_agent_events
end

Creates a dormant run for invocation.

Public Instance Methods

call ()

Source

# File lib/little_ghost/run.rb, line 149
def call
  each { |_event| }
  self
end

Consumes the event stream and returns self.

cancelled? ()

Source

# File lib/little_ghost/run.rb, line 183
def cancelled? = outcome == "cancelled"

True when cancellation stopped the run without a response.

close ()

Source

# File lib/little_ghost/run.rb, line 335
def close
  callbacks = @mutex.synchronize do
    return if @closed
    @closed = true
    @shared_resources.clear
    @shared_resource_condition.broadcast
    @resources.reverse
  end
  errors = []
  callbacks.each do |callback|
    callback.call
  rescue => error
    errors << error
  end
  cleanup_error = errors.find { |caught| caught.is_a?(CleanupError) } || errors.first
  begin
    finish_remaining_subagent_instrumentation(
      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
  error = errors.find { |caught| caught.is_a?(CleanupError) } || errors.first
  raise error if error
end

Closes registered resources in reverse order.

The operation is idempotent. It attempts every closer and then raises the first LittleGhost::CleanupError, or otherwise the first cleanup exception.

completed? ()

Source

# File lib/little_ghost/run.rb, line 174
def completed? = outcome == "completed"

True after successful completion.

context (state: {}, metadata: {})

Source

# File lib/little_ghost/run.rb, line 239
def context(state: {}, metadata: {})
  RunContext.new(
    state:,
    cancellation_token:,
    deadline: invocation.deadline_at,
    metadata:
  )
end

Creates a RunContext with this run’s cancellation token and deadline.

each () { |value| ... }

Source

# File lib/little_ghost/run.rb, line 157
def each
  return enum_for(__method__) unless block_given?

  begin_execution!
  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
  self
ensure
  @emitter = nil
end

Yields events and returns self after the terminal event.

Without a block, returns an Enumerator. A second execution raises Error.

failed? ()

Source

# File lib/little_ghost/run.rb, line 177
def failed? = outcome == "failed"

True after execution or cleanup failed.

include_agent_events? ()

Source

# File lib/little_ghost/run.rb, line 187
def include_agent_events? = @include_agent_events

Indicates whether the stream includes contextual events from every Agent that executes as part of this Run.

interject (message, interjection_id: nil, batch_key: nil, metadata: {}, cancellation_token: Support::CancellationToken.new, deadline: nil)

Source

# File lib/little_ghost/run.rb, line 193
def interject(
  message,
  interjection_id: nil,
  batch_key: nil,
  metadata: {},
  cancellation_token: Support::CancellationToken.new,
  deadline: nil
)
  interject_with do
    [
      message,
      {
        interjection_id:,
        batch_key:,
        metadata:,
        cancellation_token:,
        deadline:
      }
    ]
  end
end

Adds an interjection to the active entrypoint and waits for its response.

Raises LittleGhost::AgentInterjectionError before the entrypoint is ready or after it finishes.

once (key) { || ... }

Source

# File lib/little_ghost/run.rb, line 317
def once(key)
  @once_mutex.synchronize do
    return if @once_keys.key?(key)

    value = yield
    @once_keys[key] = true
    value
  end
end

Performs the block at most once successfully for key during this run.

Concurrent callers are serialized. The caller that performs the block receives its value; later callers receive nil. If the block raises, the key is not recorded and a later call may retry it.

partial? ()

Source

# File lib/little_ghost/run.rb, line 180
def partial? = outcome == "partial"

True when the deadline preserved a partial response.

Source

# File lib/little_ghost/run.rb, line 259
def register(resource = nil, &closer)
  callback = closer || close_callback(resource)
  @mutex.synchronize do
    raise Error, "run is already closed" if @closed
    @resources << callback
  end
  resource
end

Adds a resource or closer to reverse-order cleanup and returns the resource.

A resource must respond to close unless a block supplies the cleanup operation. Registering after the run has closed raises Error.