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. Framework-managed fields remain safe when calls overlap on threads or fibers.

Attributes

agent_operation_id [R]

Active Agent operation identifier, after the context is bound.

cancellation_token [R]

Token used to cooperatively stop the current work.

conversation_id [R]

Durable subagent conversation identifier, when present.

deadline [R]

Wall-clock deadline for the current work, when present.

metadata [R]

Framework metadata attached to this context.

state [R]

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.

Public Class Methods

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

Source

# File lib/little_ghost/run_context.rb, line 32
def initialize(
  state: {},
  cancellation_token: Support::CancellationToken.new,
  deadline: nil,
  metadata: {},
  checkpoint: nil,
  conversation_id: nil,
  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 = DataMap.new(state)
  @cancellation_token = cancellation_token
  @deadline = deadline
  @metadata = metadata.freeze
  @checkpoint = checkpoint
  @conversation_id = conversation_id
  @usage = Usage.new
  @usage_mutex = Mutex.new
  @tool_call_count = 0
  @tool_call_count_mutex = Mutex.new
  @structured_result = nil
  @structured_result_mutex = Mutex.new
  @agent_operation_id = nil
  @agent_operation_id_mutex = Mutex.new
  @interjection_mutex = Mutex.new
  @interjection_metadata = interjection_metadata&.to_h
  @interjection_ids = Array(interjection_ids).map { |id| String(id).dup.freeze }.freeze
end

Creates a context with optional checkpoint and interjection state.

Public Instance Methods

check! ()

Source

# File lib/little_ghost/run_context.rb, line 68
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 75
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 86
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 106
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 121
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 115
def submit_structured_result(result)
  @structured_result_mutex.synchronize { @structured_result = result }
  result
end

Stores a validated LittleGhost::StructuredResult and returns it.

usage ()

Source

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

Takes a snapshot of accumulated usage.