class LittleGhost::RunContext

RunContext gives tools and workflows one place for shared state, cancellation, deadlines, checkpoints, and accumulated usage. It travels with work inside a run without becoming global process state.

Tools and workflows use it to share JSON-like state, check cancellation and deadlines, checkpoint messages, and accumulate usage. Access to framework-managed fields is thread-safe.

Attributes

agent_operation_id [R]

Shared state, cancellation, deadline, metadata, operation identity, and durable conversation identity for the current work.

cancellation_token [R]

Shared state, cancellation, deadline, metadata, operation identity, and durable conversation identity for the current work.

conversation_id [R]

Shared state, cancellation, deadline, metadata, operation identity, and durable conversation identity for the current work.

Shared state, cancellation, deadline, metadata, operation identity, and durable conversation identity for the current work.

Shared state, cancellation, deadline, metadata, operation identity, and durable conversation identity for the current work.

Shared state, cancellation, deadline, metadata, operation identity, and durable conversation identity for the current work.

Public Class Methods

new (state: {}, cancellation_token: Support::CancellationToken.new, deadline: nil, metadata: {}, checkpoint: nil, conversation_id: nil, interruption_metadata: nil, interruption_ids: [])

Source

# File lib/little_ghost/run_context.rb, line 18
def initialize(
  state: {},
  cancellation_token: Support::CancellationToken.new,
  deadline: nil,
  metadata: {},
  checkpoint: nil,
  conversation_id: nil,
  interruption_metadata: nil,
  interruption_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
  @cancellation_token = cancellation_token
  @deadline = deadline
  @metadata = metadata.freeze
  @checkpoint = checkpoint
  @conversation_id = conversation_id
  @usage = Usage.new
  @usage_mutex = Mutex.new
  @structured_result = nil
  @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
end

Creates a context with optional checkpoint and interruption state.

Public Instance Methods

Source

# File lib/little_ghost/run_context.rb, line 52
def check!
  cancellation_token.raise_if_cancelled!
  raise DeadlineExceededError, "The run deadline was reached" if deadline && Time.now >= deadline
end

Raises LittleGhost::CancelledError or LittleGhost::DeadlineExceededError when execution should stop.

checkpoint (messages)

Source

# File lib/little_ghost/run_context.rb, line 59
def checkpoint(messages)
  return unless @checkpoint

  if agent_operation_id
    @checkpoint.call(messages:, state:, parent_operation_id: agent_operation_id)
  else
    @checkpoint.call(messages:, state:)
  end
end

Sends messages and current state to the configured checkpoint callback. With no checkpoint callback, this method does nothing and returns nil.

record_usage (value)

Source

# File lib/little_ghost/run_context.rb, line 70
def record_usage(value)
  @usage_mutex.synchronize { @usage += value }
end

Adds value to accumulated model usage.

remaining_time (maximum = nil)

Source

# File lib/little_ghost/run_context.rb, line 83
def remaining_time(maximum = nil)
  check!
  return maximum unless deadline

  remaining = deadline - Time.now
  maximum ? [remaining, maximum].min : remaining
end

Calculates seconds remaining before the deadline.

When maximum is provided, the result is capped at that value. With no deadline, returns maximum.

structured_result ()

Source

# File lib/little_ghost/run_context.rb, line 98
def structured_result
  @structured_result_mutex.synchronize { @structured_result }
end

Finds the latest validated structured result, if any.

submit_structured_result (result)

Source

# File lib/little_ghost/run_context.rb, line 92
def submit_structured_result(result)
  @structured_result_mutex.synchronize { @structured_result = result }
  result
end

Stores a validated LittleGhost::StructuredResult and returns it.

Source

# File lib/little_ghost/run_context.rb, line 75
def usage
  @usage_mutex.synchronize { @usage }
end

Takes a snapshot of accumulated usage.