---
title: "Sessions"
description: "Agent execution, shared history reads, writer fences, and recovery."
url: "https://ankole.agentbull.com/en-US/docs/sessions/"
lang: "en-US"
---

> Documentation index for AI Agents: https://ankole.agentbull.com/en-US/llms.txt

# Sessions

A Session is a single Agent's unit of execution, keyed by `{agent_uid, session_id}`. An Agent can run multiple Sessions concurrently, and each Session advances through a dedicated Driver process in `Ankole.Sessions`.

While a Conversation stores the shared message stream visible to participants, each Agent in that Conversation owns its own separate Session, and AIGateway stores the model transcript used by that Session. Generic business Signals can also target a Session directly without any backing Conversation.

## One writer

Under `Ankole.Sessions`, a `DynamicSupervisor` starts temporary `:gen_statem` Driver processes, and `:global` registers at most one active Driver name per `{agent_uid, session_id}` across the Erlang cluster. To guard against split-brain writes, Ankole uses a persistent workspace epoch as a write fence: signal admission increments the epoch, and every Driver transaction verifies that epoch under a row lock so a stale Driver isolated by a network partition cannot commit.

## Durable inputs and model history

Signals serve as the Session's durable inbox, while AIGateway's Response chain records model outputs and tool results. When a control-plane tool executes, Ankole commits its domain side effect and a receipt atomically; once the tool round finishes, the Driver appends the completed round to the AIGateway chain and deletes those receipts in a single transaction. If a Driver crashes, its replacement reconstructs the exact in-flight state from these persisted records.

At each model request boundary, `Ankole.Sessions` reads new Conversation Messages using a read watermark stored in the request metadata, excluding the current main and steering Messages from the background context slice. Although shared Conversation history supplies conversational context, it never grants the Agent authority to act on behalf of an earlier speaker—admission always evaluates the Principal of the current requester.

When a turn finishes, the Driver commits Signal completion and the final outbound reply intent together, preserving the original reply owner across internal revisions and keeping completed tool results available across withdrawals or retries. Ordinary Agent replies in shared rooms never wake other Agents; instead, explicit Agent-to-Agent collaboration uses `send_to_agent` to open an isolated `agent_peer` exchange from a `personal_assistant` to an `ai_colleague` under the owner's frozen Human `WorkAccess`—projecting any colleague `Clarify` question or `ActionCard` directly into the origin conversation (zero-hop pass-through) so human answers wake the colleague directly, and delivering the colleague's committed reply back to the assistant Session as a durable Signal. Slash commands such as `/compress` commit their user feedback and compaction checkpoint directly without requiring a final language-model Response.

## Cold-wake model conversation rotation

On conversation admission (`Ankole.Sessions.WakeRecycle`, configured through `sessions.wake_recycle`), Ankole rotates an active AIGateway model conversation onto a successor branch inside the admission transaction whenever the predecessor has completed at least one Response and either (a) idle time reaches `min_cold_gap_seconds` (default `3,600` seconds) with cumulative input context at or above `min_context_tokens` (default `128,000` tokens), or (b) an external IM conversation sits idle for at least `im_max_idle_seconds` (default `259,200` seconds / 72 hours).

Rotation skips explicit `/new` resets (`command.new`), interactive card answers and callbacks, background callback Signals (`background_agent_job.*` and `workflow.run.*`), Sessions with open or waiting `BackgroundAgentJob` or `Workflow.Run` records or another running Signal, and crash retries (`last_attempt_at != nil`). Ankole carries forward unresolved `InteractionState` and `ActionCard` checkpoints while leaving public `conversation_messages` untouched, and before the successor's first model request `Sessions.WakeBriefing` injects a deterministic `<wake-briefing>` block capped at `8,000` `o200k_base` tokens (`<brain-memory>`, `<recent-messages>`, `<recent-actions>`, and `<objects-in-play>`).

## Worker and operation identity

Agent creation requests an initial Worker startup in the background. During Session execution, `Ankole.Sessions` requests the Worker when an environment tool or Codex Job needs a computer; pure questions do not wake a Worker that has been released after going idle. Environment operations carry a `RunRef` scoped to the Agent, Session, and Signal, whereas Codex turns carry a `JobTurnRef` that additionally identifies the Job and attempt. Because each operation has its own stable identity, a replacement Driver can adopt Worker operations that are already running rather than duplicating them.

RuntimeFabric maintains one Phoenix Channel per Worker and locates active sockets across cluster nodes via Phoenix Tracker. On every message, RuntimeFabric checks the Worker's generation and incarnation numbers to reject stale routes, ensuring each Worker remains exclusively bound to a single Agent.

## Recovery

During signal admission, `Ankole.Signals` inserts a durable Oban wakeup job inside the same PostgreSQL transaction as the caller's domain writes. Periodically, a Reconciler scans due open Signals—including attempts that have already started—and either nudges the live Driver or starts a fresh one; it also asks the Workflow subsystem to recover missing `RunServers` and run pending cleanups. Persisted `last_attempt_at` timestamps and failure budgets bound repeated retry attempts.

Native Pod chats, external chat channels, scheduled runs, and business events all share this Session execution model. Read [Signals](https://ankole.agentbull.com/en-US/docs/signals/index.md), [Agent loop](https://ankole.agentbull.com/en-US/docs/agent-loop/index.md), and [Agent Computer Worker](https://ankole.agentbull.com/en-US/docs/agent-computer-worker/index.md) for the adjacent subsystems.
