class LittleGhost::Execution

Runs one dormant Run in the background while the caller remains free to serve health checks, deliver interjections, or coordinate shutdown.

execution = agent.start_execution(message: "Investigate transfer 481") do |event|
  event_buffer << event
end

execution.interject(message: "Include the latest ledger entry")
execution.wait(deadline: Time.now + 30)
execution.run.completed? # => true

The Runtime selects a scheduled fiber or worker thread for the execution. LittleGhost copies the caller’s ExecutionState, but not other application fiber-local or thread-local values. The Run continues to own its workspace, sandbox, session, entrypoint, and registered resources. close requests cooperative cancellation and waits for the execution and any in-flight interjection calls.

Attributes

run [R]

The supervised Run.

Public Class Methods

start (run, &event_consumer)

Source

# File lib/little_ghost/execution.rb, line 33
def start(run, &event_consumer)
  new(run, event_consumer:).send(:start)
end

Starts run immediately and returns its supervising Execution. If the work cannot start, this method closes run before raising.

The optional block receives each StreamEvent from the fiber or thread running the Execution. It must not depend on a particular thread and should not pause the scheduler or retain sensitive event content longer than the application requires.

Public Instance Methods

active? ()

Source

# File lib/little_ghost/execution.rb, line 65
def active?
  @mutex.synchronize { @state != :finished || @active_interjections.positive? }
end

Indicates that the Execution or an interjection call is still active.

cancel ()

Source

# File lib/little_ghost/execution.rb, line 97
def cancel
  run.cancellation_token.cancel
  self
end

Requests cooperative cancellation and returns self.

close (deadline: nil)

Source

# File lib/little_ghost/execution.rb, line 118
def close(deadline: nil)
  @mutex.synchronize { @closing = true }
  cancel
  wait(deadline:)
end

Prevents new interjections, requests cancellation, and waits for shutdown. The operation is idempotent. deadline has the same meaning as in wait.

error ()

Source

# File lib/little_ghost/execution.rb, line 60
def error
  @mutex.synchronize { @worker }&.error
end

Returns an event-delivery or cleanup exception raised by the Execution.

finished? ()

Source

# File lib/little_ghost/execution.rb, line 70
def finished?
  !active?
end

Indicates that the Execution and all interjection calls have finished.

interject (payload = nil, **options)

Source

# File lib/little_ghost/execution.rb, line 81
def interject(payload = nil, **options)
  if payload.nil? && options.key?(:message)
    payload = options.delete(:message)
  end
  interjection_started = false
  begin_interjection!
  interjection_started = true
  run.interject_with do
    prepared = run.prepare_interjection(interjection_payload(payload, options))
    interjection_arguments(prepared, options)
  end
ensure
  finish_interjection! if interjection_started
end

Prepares and delivers one interjection to the active run.

payload may be a message or a Hash containing message and the options accepted by Run#interject. Runtime hooks receive the Hash before delivery, allowing them to materialize trusted application attachments. Calls may overlap, but close prevents new calls and waits for calls that have already begun.

state ()

Source

# File lib/little_ghost/execution.rb, line 55
def state
  @mutex.synchronize { @state }
end

Returns :pending, :running, or :finished.

wait (deadline: nil)

Source

# File lib/little_ghost/execution.rb, line 107
def wait(deadline: nil)
  worker = wait_until_finished(deadline:)
  worker.wait
  caught = worker.error
  raise caught if caught

  run
end

Waits for the Execution and in-flight interjections, then returns the Run.

deadline is an absolute Time. Reaching it raises DeadlineExceededError without cancelling the run. An event-delivery or cleanup failure raised by the Execution is re-raised after all supervised work finishes.