Sessions

A session preserves a conversation's messages, tool activity, clarifications, Role, model and branch state. It belongs to the selected Profile. Closing Dashboard or the TUI does not delete its history.

Session history lives in state.db and referenced objects. Cross-session personal memory is separate: memory/USER.md and memory/MEMORY.md. A context summary is not a new memory entry.

Start and resume

In Dashboard, select New session, or choose an existing chat. The Chats tab contains ordinary conversations; Background contains scheduled, delegated and resident background work. Older sessions and messages load in pages.

In the TUI, run anyy, then use /new or /sessions. Open a known conversation directly:

anyy --resume SESSION_ID

Choose a Role for a new conversation:

anyy --role scribe
anyy chat --role scribe "Help me plan this article"

A resumed session keeps its Role. --role cannot be combined with --resume or chat --session. Session IDs are resolved only within the selected Profile.

Send a CLI turn

anyy chat "Summarize my priorities"
anyy chat --session SESSION_ID --json "Add the new constraint"

anyy chat requires a running Gateway. It waits for the original accepted input and its actual run, even when later turns reuse the same session. --json includes the session, submission, execution and run IDs, outcome, and recorded answer. A later success cannot replace an earlier failure.

Clarification suspension, failure, interruption, cleared input and wait timeout return nonzero. A timeout or caller cancellation stops waiting, not the accepted work. Check the session before submitting the prompt again. See CLI results.

Pending messages

Each session has two independent input queues:

• Steering is read at the agent's next steering checkpoint. It does not cancel a running tool.
• Follow-up waits until the current response finishes.

Dashboard has one Send button. While busy, sending adds a follow-up above the composer. Each waiting item offers Steer, Edit, and Delete. Steer moves it to the pending conversation for the next checkpoint. Edit changes only that waiting item, retaining attachments unless removed; canceling the editor leaves it unchanged. Delete removes that waiting item. An already selected input cannot be edited or deleted as a queue item. Conflicting changes refresh the queue and preserve the unsent draft. See Dashboard Chat.

In the TUI, busy Enter inserts steering and Alt+Enter adds a follow-up. The queue shows steering first, then follow-ups. Alt+Up returns all waiting text and attachments to the editor without stopping work. The returned text comes before your existing draft, separated by blank lines. Only a successful Gateway acknowledgement clears queue membership; sending the revised draft admits a new input.

Stop versus return to editor

Action	Active work	Pending inputs
Dashboard Escape	Stops the reply displayed at the keypress	Retained
TUI Ctrl+C while busy	Stops current Session work	Retained
TUI streaming Esc	Returns inputs, then stops the captured turn	Returned to editor
TUI Alt+Up	Continues	Returned to editor
TUI Esc during retry backoff	Cancels that retry wait	Unchanged

Local pickers and overlays handle Escape first. Delayed Dashboard stop and TUI return-to-editor acknowledgements cannot interrupt a later turn. Abort waits for captured work to settle and preserves committed history. It does not automatically start another invocation; a later prompt or an explicit Session continuation resumes work.

API queue controls

Connected clients can inspect pending inputs with session.queue.peek/session.queue.list, return cleared inputs with session.queue.clear, and change waiting items with session.queue.steer, .update and .cancel. Clearing queue membership preserves the recorded input body; it is not transcript deletion.

session.queue.modes independently reads or sets steering and follow_up to all or one-at-a-time. These choose whether a checkpoint takes all eligible messages or one at a time; they do not change steering into follow-up. These are RPC controls, not /queue commands or Dashboard queue-mode settings.

Model and tool settings

Dashboard's model selector and TUI /provider, /model and /effort control the current session. Profile model defaults seed new sessions. Resuming or navigating a branch restores the applicable session selection; if a previously selected virtual model is no longer registered, Anyy can fall back to the latest physical reply's model.

Roles define identity and Soul instructions. They do not select tool names or Codemode mode. Use the CLI tool flags or session.tools.configure for a Session tool selection. An explicit update requires an idle session without queued/admitting work or a summary operation. The Tools/Codemode settings belong to the Profile.

Reload resources

The session.reload RPC refreshes an idle session from current Profile settings and resources while retaining history, its selected store, loaded tools and pending inputs. It does not stop active work or start a new turn. Resource loading is ordered; an error does not imply that every earlier resource change rolled back. There is no matching Dashboard button, TUI command or shell subcommand.

Goal metadata API

session.goal stores optional goal text and an active or paused state in the session metadata. Clients can use set, status, pause, resume and clear. It does not start or stop a run, create a scheduled job, or autonomously continue until completion. It is separate from personal task records. Dashboard and TUI do not expose /goal, and the shell CLI has no goal subcommand.

Retries and context size

Transient model errors are retried automatically by default, at most three times after the first request. Backoff starts at two seconds and grows exponentially to a one-minute cap. These Session settings are shared by the Profile; provider transport retries are a separate layer. During a retry wait, TUI Esc cancels only the wait. Ctrl+C or Dashboard Escape stops work.

Compaction and branch summaries share the Profile retry policy. An operation retains its retry budget; later model calls still read current transport defaults. Disabling automatic retry does not disable HTTP timeouts. A failed, canceled or truncated summary is not applied. See Context compaction for automatic context recovery and the available manual API.

Navigate existing history

TUI /tree opens the current conversation tree while idle. Use Up/Down, Enter to select, s to toggle a summary of the branch being left, and Esc to cancel. Selecting a user message moves to the point before it and returns its text to an empty composer for revision. Preserve a draft before navigating if you want the returned text. Navigation stays within the same Session and starts no model reply. Earlier and sibling branches remain in the tree.

Fork and deletion APIs

session.fork creates a separate conversation from a selected point and preserves that path's history and labels. Forking before a user message can return its text for revision without resending it. It does not copy running work, pending queues or Channel sending permissions.

Forking also affects the original conversation: it captures that session's current work before preparing the fork. Once the new conversation is durably saved, Anyy interrupts the captured work and waits for it to settle. A delayed stop does not interrupt a subsequent turn. If settlement fails, the new conversation remains saved; an error does not imply that the fork was rolled back.

session.delete removes a conversation while preserving history still referenced by another fork. If the session has nonterminal work, deletion returns a conflict; it does not automatically stop that work and then delete the session.

Fork and individual session deletion are public RPC capabilities. The current Dashboard, TUI and shell CLI have no fork/delete action. TUI /tree is navigation within one conversation, rather than a fork command.

Troubleshooting

Problem	Check
A conversation is missing	Selected Profile and Chats/Background tab
/sessions or /tree cannot open	Wait for the turn to finish or stop it first
A correction should affect ongoing work	Dashboard: send, then Steer; TUI: busy Enter
A queued message cannot be edited	It may already have been selected; inspect refreshed history
CLI chat cannot connect	Run anyy gateway start for that Profile
Old Role or model state appears after resume	The session owns that state; select a model or start a new session for new defaults

Profile backup includes durable session data. Use one session per sustained topic and start a new one when earlier context is no longer useful.