class LittleGhost::Runtime

Prepare the shared services that agents and workflows use across many runs. A runtime owns model resolution, loading, persistence, lookup paths, hooks, and resource factories for one Ruby setup.

configuration = LittleGhost::Configuration.new(
  root: Dir.pwd,
  models: CustomerSupportModels,
  default_model: "customer_support",
  service_name: "support-api"
)
runtime = LittleGhost::Runtime.new(configuration: configuration)

runtime.service_name # => "support-api"
runtime.root == Pathname.new(File.realpath(Dir.pwd)) # => true

Without explicit settings, construction canonicalizes the root, loads config/little_ghost.rb once through the Configuration, snapshots settings, configures instrumentation, eager-loads application constants, and builds the selected model registry and session store. Supplying settings is the lower-level path used to create a sibling runtime from an existing snapshot.

Reuse a runtime across runs. build_run creates any missing workspace and sandbox, transfers ownership only after both are built, and closes partial resources if construction fails. build creates a sibling with explicit overrides and reuses the loader only when the application root is unchanged.

Startup emits structured lifecycle instrumentation; a failed phase emits a failure event, flushes instrumentation, and re-raises the original exception. Session actor resolution must use trusted authenticated identity for tenant isolation. The default UnrestrictedSandbox is convenient application plumbing, not a security boundary for untrusted work.

Attributes

configuration [R]

The snapshotted setup and materialized services used by new runs.

The snapshotted setup and materialized services used by new runs.

The snapshotted setup and materialized services used by new runs.

prompt_paths [R]

The snapshotted setup and materialized services used by new runs.

The snapshotted setup and materialized services used by new runs.

runtime_hooks [R]

The snapshotted setup and materialized services used by new runs.

sandbox_class [R]

The snapshotted setup and materialized services used by new runs.

session_store [R]

The snapshotted setup and materialized services used by new runs.

The snapshotted setup and materialized services used by new runs.

skill_paths [R]

The snapshotted setup and materialized services used by new runs.

skill_resource_root [R]

The snapshotted setup and materialized services used by new runs.

workspace_class [R]

The snapshotted setup and materialized services used by new runs.

Public Class Methods

new (configuration:, settings: nil)

Source

# File lib/little_ghost/runtime.rb, line 45
def initialize(configuration:, settings: nil)
  @startup_started_at = monotonic_time
  @startup_phase = "configuration"
  @startup_reported = false

  begin
    raise ArgumentError, "configuration must be a LittleGhost::Configuration" unless configuration.is_a?(Configuration)

    @configuration = configuration
    if settings
      @settings = settings
    else
      bootstrap_root = canonical_application_root(configuration.root)
      configuration.load_file!(root: bootstrap_root)
      @settings = configuration.settings(root: bootstrap_root)
    end
    report_startup(status: "starting")
    @startup_reported = true
    @root = canonical_application_root(@settings.fetch(:root))
    @skill_resource_root = @settings[:skill_resource_root]
    @workspace_class = @settings.fetch(:workspace)
    @sandbox_class = @settings.fetch(:sandbox)
    @runtime_hooks = build_runtime_hooks(@settings[:runtime_hooks])

    @startup_phase = "instrumentation"
    subscribe_instrumentation(@settings[:instrumentation_subscribers])
    emit_startup(:runtime_start)

    @startup_phase = "loader"
    @loader = @settings[:loader] || Support::Loader.new(root: @root)
    loader.setup
    loader.eager_load

    @startup_phase = "models"
    @invocation_class = @settings[:invocation] || Invocation
    @models = build_service(@settings[:models], default: -> { DefaultModelRegistry.new })
    @default_model = @settings.fetch(:default_model, "default").to_s

    @startup_phase = "session_store"
    @session_store = build_session_store(@settings[:session_store])
    @session_actor = @settings[:session_actor]

    @startup_phase = "prompts"
    @prompt_paths = build_lookup_paths(:prompt_paths)
    @skill_paths = build_lookup_paths(:skill_paths)

    @startup_phase = "agent_builder"
    @agent_builder = AgentBuilder.new(
      runtime: self,
      prompt_paths: @prompt_paths,
      resolve_agent: method(:resolve_agent_class)
    )

    @startup_phase = "complete"
    emit_startup(:runtime_stop, outcome: "ready")
    report_startup(status: "ready")
  rescue => error
    unless @startup_reported
      report_startup(status: "starting")
      @startup_reported = true
    end
    emit_startup(:runtime_stop, outcome: "failed", error:)
    Instrumentation.flush
    report_startup(status: "failed", error:)
    raise
  end
end

Starts a runtime from configuration or an existing settings snapshot.

Public Instance Methods

build (**overrides)

Source

# File lib/little_ghost/runtime.rb, line 114
def build(**overrides)
  values = @settings.merge(overrides)
  values[:root] = canonical_application_root(values.fetch(:root))
  values[:loader] = loader unless overrides.key?(:loader) || overrides.key?(:root)
  self.class.new(
    configuration:,
    settings: values
  )
end

Creates a sibling runtime with explicit setting overrides.

build_run (payload, agent_class:, entrypoint_class: agent_class, workspace: nil, sandbox: nil)

Source

# File lib/little_ghost/runtime.rb, line 131
def build_run(
  payload,
  agent_class:,
  entrypoint_class: agent_class,
  workspace: nil,
  sandbox: nil
)
  owned_resources = []
  workspace ||= build_workspace.tap { |resource| owned_resources << resource }
  sandbox ||= build_sandbox(workspace:).tap { |resource| owned_resources << resource }
  run = Run.new(
    invocation: parse(payload),
    runtime: self,
    agent_class:,
    entrypoint_class:,
    workspace:,
    sandbox:
  )
  owned_resources.each { |resource| run.register(resource) }
  prepare_run(run)
rescue
  if run
    run.close
  else
    close_resources(owned_resources)
  end
  raise
end

Creates a Run and transfers ownership of newly created workspace and sandbox resources to it.

build_sandbox (workspace:)

Source

# File lib/little_ghost/runtime.rb, line 169
def build_sandbox(workspace:)
  return sandbox_class.new(workspace:) if sandbox_class

  UnrestrictedSandbox.new(workspace:)
end

Instantiates the configured sandbox around workspace, or an unrestricted sandbox by default.

build_workspace ()

Source

# File lib/little_ghost/runtime.rb, line 161
def build_workspace
  return workspace_class.new if workspace_class

  Workspace.new(root: root)
end

Instantiates the configured workspace, or a root-scoped Workspace by default.

parse (payload)

Source

# File lib/little_ghost/runtime.rb, line 125
def parse(payload)
  payload.is_a?(@invocation_class) ? payload : @invocation_class.new(payload)
end

Coerces an application payload into the configured Invocation class.