Class: Session

Inherits:
ApplicationRecord show all
Defined in:
app/models/session.rb

Overview

A conversation session — the fundamental unit of agent interaction. Owns an ordered stream of Event records representing everything that happened: user messages, agent responses, tool calls, etc.

Constant Summary collapse

DEFAULT_TOKEN_BUDGET =

Claude Sonnet 4 context window minus system prompt reserve.

190_000
VIEW_MODES = 
%w[basic verbose debug].freeze

Instance Method Summary collapse

Instance Method Details

#messages_for_llm(token_budget: DEFAULT_TOKEN_BUDGET) ⇒ Array<Hash>

Builds the message array expected by the Anthropic Messages API. Includes user/agent messages and tool call/response events in Anthropic’s wire format. Consecutive tool_call events are grouped into a single assistant message; consecutive tool_response events are grouped into a single user message with tool_result blocks. Pending messages are excluded — they haven’t been delivered yet.

Parameters:

  • token_budget (Integer) (defaults to: DEFAULT_TOKEN_BUDGET) —

    maximum tokens to include (positive)

Returns:

  • (Array<Hash>) —

    Anthropic Messages API format



70
71
72
 
# File 'app/models/session.rb', line 70

def messages_for_llm(token_budget: DEFAULT_TOKEN_BUDGET)
  assemble_messages(viewport_events(token_budget: token_budget, include_pending: false))
end

#next_view_mode ⇒ String

Cycles to the next view mode: basic → verbose → debug → basic.

Returns:

  • (String) —

    the next view mode in the cycle



21
22
23
24
 
# File 'app/models/session.rb', line 21

def next_view_mode
  current_index = VIEW_MODES.index(view_mode) || 0
  VIEW_MODES[(current_index + 1) % VIEW_MODES.size]
end

#promote_pending_messages! ⇒ Integer

Promotes all pending user messages to delivered status so they appear in the next LLM context. Triggers broadcast_update for each event so connected clients refresh the pending indicator.

Returns:

  • (Integer) —

    number of promoted messages



79
80
81
82
83
84
85
86
 
# File 'app/models/session.rb', line 79

def promote_pending_messages!
  promoted = 0
  events.where(event_type: "user_message", status: Event::PENDING_STATUS).find_each do |event|
    event.update!(status: nil, payload: event.payload.except("status"))
    promoted += 1
  end
  promoted
end

#system_prompt ⇒ String?

Returns the assembled system prompt for this session. The system prompt includes system instructions, goals, and memories. Currently a placeholder — these subsystems are not yet implemented.

Returns:

  • (String, nil) —

    the system prompt text, or nil if not configured



57
58
59
 
# File 'app/models/session.rb', line 57

def system_prompt
  nil
end

#viewport_events(token_budget: DEFAULT_TOKEN_BUDGET, include_pending: true) ⇒ Array<Event>

Returns the events currently visible in the LLM context window. Walks events newest-first and includes them until the token budget is exhausted. Events are full-size or excluded entirely.

Parameters:

  • token_budget (Integer) (defaults to: DEFAULT_TOKEN_BUDGET) —

    maximum tokens to include (positive)

  • include_pending (Boolean) (defaults to: true) —

    whether to include pending messages (true for display, false for LLM context assembly)

Returns:

  • (Array<Event>) —

    chronologically ordered



34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'app/models/session.rb', line 34

def viewport_events(token_budget: DEFAULT_TOKEN_BUDGET, include_pending: true)
  scope = events.context_events
  scope = scope.deliverable unless include_pending

  selected = []
  remaining = token_budget

  scope.reorder(id: :desc).each do |event|
    cost = (event.token_count > 0) ? event.token_count : estimate_tokens(event)
    break if cost > remaining && selected.any?

    selected << event
    remaining -= cost
  end

  selected.reverse
end