core/session

Session state — holds conversation context per agent. Pure state transformer, no OTP. The CLI harness drives it.

For persistence, use load/persist which delegate to session_db.

Types

Session

pub type Session {
  Session(
    session_id: String,
    persona: String,
    history: List(completions.Message),
    persisted_message_count: Int,
    turn_count: Int,
  )
}

Constructors

Session(
  session_id: String,
  persona: String,
  history: List(completions.Message),
  persisted_message_count: Int,
  turn_count: Int,
)

Values

end_and_fork

</>

pub fn end_and_fork(
  conn: sqlight.Connection,
  session: Session,
  source: String,
  persona: String,
  reason: String,
) -> Result(#(Session, String), String)

End the current session and create a new one linked via parent_session_id. Returns both the new Session and its session_key (needed by the REPL for context injection — session.session_id is the internal DB UUID, not the key).

generate_session_key

</>

pub fn generate_session_key(source: String) -> String

Generate a unique session key with source and ISO8601 timestamp.

handle_message

</>

pub fn handle_message(
  session: Session,
  client: completions.Client,
  user_message: String,
  tool_defs: List(completions.ToolDefinition),
  max_rounds: Int,
  conn: sqlight.Connection,
  user_key: String,
) -> #(String, Session)

Process a user message through the conversation loop (default tool registry). Returns the reply text and the updated session.

handle_message_with

</>

pub fn handle_message_with(
  session: Session,
  client: completions.Client,
  user_message: String,
  tool_defs: List(completions.ToolDefinition),
  max_rounds: Int,
  all_tools: List(tool.Tool),
  conn: sqlight.Connection,
  user_key: String,
) -> #(String, Session)

Process a user message with a custom tool list (e.g. approval-enabled bash).

load

</>

pub fn load(
  conn: sqlight.Connection,
  session_key: String,
  source: String,
  persona: String,
) -> Result(Session, String)

Load a session from the database, or create it if it doesn’t exist.

new

</>

pub fn new(session_id: String, persona: String) -> Session

Create a new in-memory session with an id and persona.

persist

</>

pub fn persist(
  conn: sqlight.Connection,
  session: Session,
) -> Result(Session, String)

Persist new messages since last save and bump the updated_at timestamp.