Session

Source: core/session/session.gleam, core/session/handler.gleam

Session management covers conversation state (message lists, metadata, parent lineage) and the adapter layer that wires the session with the loop runner.

Modules

session.gleam

Pure state transformer for conversation context. Manages message lists, session metadata, and parent lineage. Imports services/storage/session_db (Blessed Violator #5) for persistence operations.

The Session record holds:

Field	Description
session_id	Database row ID
persona	Active persona name
history	Full List(Message) for the conversation
persisted_message_count	Number of messages already saved to DB
turn_count	Turns completed in the current session

Key functions:

• new(session_id, persona) -- creates an empty in-memory session
• load(conn, session_key, source, persona) -- loads from DB or creates if not found
• persist(conn, session) -- saves only new messages since last persist; bumps updated_at
• generate_session_key(source) -- produces a unique key: source:UUID
• end_and_fork(conn, session, source, persona, reason) -- ends the current session and creates a new child session linked via parent_session_id

handler.gleam

Composition/adapter layer (Blessed Violator #4). Wires session state, loop runner, registry builder, and reflection hook. This is the entry point for processing a new user message.

Flow: load session -> run loop -> persist results -> maybe reflect.

Key functions:

• handle_message(session, client, user_message, ...) -- runs the loop with default tool registry and auto-deny approvals
• handle_message_with(session, client, user_message, ..., all_tools, approval_handler, ...) -- runs with a custom tool list and approval handler

After each completed turn (Success or ToolLoopLimit), the handler checks whether reflection is enabled. If so, and if the turn count meets the configured interval, it spawns an async review agent that consolidates important information into persistent memory.

Related Pages

• Loop -- The orchestrator invoked by the session handler
• Registry -- Tool registry wired by the handler
• Blessed Violators -- Why handler.gleam and session.gleam can import services