Skip to content
Ankole

Sessions

For AI Agents: the Markdown version of this page is at https://ankole.agentbull.com/en-US/docs/sessions/index.md. The documentation index is at https://ankole.agentbull.com/en-US/llms.txt.

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, Agent loop, and Agent Computer Worker for the adjacent subsystems.