class Riffer::Agent::Context

Typed value object wrapping the runtime context Hash held by a Riffer::Agent. Exposes first-class accessors for the framework-managed entries — skills and token_usage — and preserves [] / dig reads so tools (which receive context: as a keyword) keep working with both built-in and caller-provided keys.

Reserved keys (:skills, :token_usage) cannot be set by the caller at construction; they are owned by Riffer and written through the typed setters. Type invariants are enforced on write — skills must be a Riffer::Skills::Context (or nil); token_usage must be a Riffer::Providers::TokenUsage (or nil).

context = Riffer::Agent::Context.new(user_id: 42)
context[:user_id]    # => 42
context.skills       # => nil
context.token_usage  # => nil

Constants

RESERVED_KEYS: Keys reserved for framework use. Passing any of these to the constructor raises Riffer::ArgumentError.

Public Class Methods

new (data = {})

Source

# File lib/riffer/agent/context.rb, line 36
def initialize(data = {})
  reserved = data.keys & RESERVED_KEYS
  if reserved.any?
    raise Riffer::ArgumentError,
      "Reserved keys cannot be passed in context: #{reserved.join(", ")}"
  end

  @data = data.dup
  @data[:skills] = nil
  @data[:token_usage] = nil
end

Builds a new context.

data: caller-provided Hash passed as Agent.new(context:). Duped before storage so caller mutations do not affect the agent. Must not contain any RESERVED_KEYS.

Raises Riffer::ArgumentError when data contains a reserved key.

Public Instance Methods

[] (key)

Source

# File lib/riffer/agent/context.rb, line 104
def [](key)
  @data[key]
end

Hash-style read. Preserved so downstream tool runtimes pulling caller-provided keys via context[:agent] or context[:tenant] keep working unchanged.

dig (*keys)

Source

# File lib/riffer/agent/context.rb, line 113
def dig(*keys)
  @data.dig(*keys)
end

Hash-style dig. Preserved for tools using context&.dig(:user_id).

skills ()

Source

# File lib/riffer/agent/context.rb, line 53
def skills
  @data[:skills]
end

The agent’s resolved Riffer::Skills::Context, or nil when skills are not configured.

skills= (value)

Source

# File lib/riffer/agent/context.rb, line 65
def skills=(value)
  unless value.nil? || value.is_a?(Riffer::Skills::Context)
    raise Riffer::ArgumentError,
      "skills must be a Riffer::Skills::Context or nil, got #{value.class}"
  end
  @data[:skills] = value
end

Sets the resolved skills context. Called once by Riffer::Agent during construction.

Raises Riffer::ArgumentError if value is neither nil nor a Riffer::Skills::Context.

to_h ()

Source

# File lib/riffer/agent/context.rb, line 122
def to_h
  @data.dup
end

Returns a copy of the underlying Hash. Mutating the result does not affect this context.

token_usage ()

Source

# File lib/riffer/agent/context.rb, line 78
def token_usage
  @data[:token_usage]
end

The cumulative Riffer::Providers::TokenUsage across every Run on this agent, or nil before the first response is recorded.

token_usage= (value)

Source

# File lib/riffer/agent/context.rb, line 90
def token_usage=(value)
  unless value.nil? || value.is_a?(Riffer::Providers::TokenUsage)
    raise Riffer::ArgumentError,
      "token_usage must be a Riffer::Providers::TokenUsage or nil, got #{value.class}"
  end
  @data[:token_usage] = value
end

Sets the cumulative token usage. Called by Riffer::Agent::Run after each LLM response.

Raises Riffer::ArgumentError if value is neither nil nor a Riffer::Providers::TokenUsage.