Sessions, turns, and threads

A Veyyon run is a loop of user requests and agent responses. The session holds the whole run. Each turn is one request and the agent loop that answers it. A thread is one path through the session tree. These three ideas are the foundation for branching, plan mode, and long-running context.

Lifecycle of a run

start session (veyyon / veyyon "prompt" / resume)
        │
        ▼
compose prompt ──► turn begins
        │
        ├─ assemble context (instructions, goal card, recent history, tools)
        ├─ call model
        ├─ dispatch / repair tool calls (edit, exec, MCP, …)
        ├─ approval-mode gate
        └─ final reply ──► turn ends (or Esc abort)
        │
        ▼
append rollout entry ──► update active leaf
        │
        ├─ next user message ──► next turn
        ├─ /compact when the window is tight
        └─ /fork / /branch / /tree when exploring branches

Interactive veyyon, a non-interactive veyyon "prompt" run, and resume paths all share this loop. The difference is who supplies the next prompt and whether a TUI is attached.

What a session is

A session is the unit of interactive work. Start one with veyyon in the repository you want to change. The session records every turn, tool call, approval, edit, and verification result.

Sessions are stored as append-oriented rollout JSONL files. Each history entry has an id and a parentId, which makes the rollout a tree rather than a linear chat log. New history is appended. Header or representation maintenance may atomically rewrite the file, but it preserves every history entry.

What a turn is

A turn is one user request plus the agent loop that responds to it. The loop calls the model, dispatches any tool calls, and produces the final reply. A turn ends when the model stops or when the harness decides to stop it.

While a turn runs you can steer it with Enter or queue a follow-up with ctrl+q or ctrl+enter. A queued follow-up becomes a new turn after the current one finishes. Interrupting with Esc aborts the turn and returns queued messages to the composer.

Threads and the active leaf

At any moment, one path through the session tree is active. That path is the thread. The active leaf is the current entry at the end of that path.

Branching creates siblings in the tree. /tree browses every entry, including abandoned branches. /branch copies history up to a chosen user message into a new session file. /fork duplicates the entire current session into a new file (no entry picker). There is no /clone command. The original session is never modified.

Context pressure and compaction

Models have a finite token window. As a session grows, the raw transcript may no longer fit. Veyyon compacts history into a smaller, information-preserving summary instead of truncating it.

Compaction preserves the goal card, active user instructions, recent turns, and a deterministic working-set of files touched so a resumed session does not require the full raw transcript.

Prefer /compact when you need a summary to retain state. Prefer the /new command when prior transcript is no longer useful and you want a clean session without summarization. See Slash commands.

The rollout

Session history lives in one layer: the JSONL rollout. Every event is one line: a user message, an agent response, a tool call, a compaction, a goal update, or a branch summary. The rollout is the only source of truth. Listing and resume read it through the active storage backend, including indexed Redis and SQL storage. A non-empty rollout without a valid header is rejected without changing its bytes; malformed later records are skipped with an operator-visible path, line, byte, and shape warning. Goal cards persist as rollout entries. There is no separate session-state database.

How the pieces relate

• A session contains one or more threads and stores them on disk.
• A thread is a path through the session’s tree of turns.
• A turn is one step on that path.
• The rollout is the append-only log that holds every turn, branch, and system event.
• The goal card is a separate context slot that contains the current objective across turns and compactions. See Goal state and long sessions.

Where the details live

• For session commands and storage, see Sessions.
• For branching, forking, and cloning, see Session branching.
• For plan mode and goal tracking, see Plan mode and goals.
• For how compaction works, see Compaction and project memory.
• For goal state and long sessions, see Goal state and long sessions.
• For contributor-facing internals, see Session and turn internals.