English | 简体中文
This document describes the goals, direction, and boundaries of the tinyagent Sessions module.
Sessions provide recoverable, auditable conversation state for each Workspace. Users can continue a conversation after the process exits and can determine exactly what was saved when a provider or tool fails.
The module's primary goals are to:
- persist Sessions, Messages, and Runs;
- isolate state between Workspaces;
- recover safely after an abnormal process exit or failed database migration;
- provide consistent session-management semantics across the CLI and SDK;
- retain complete original history for auditing, context selection, and later compaction.
Only the .tinyagent/workspace-id identity marker is stored in the Workspace. Transactional data lives outside the Workspace by default:
~/.tinyagent/workspaces/<workspace-uuid>/state.sqlite3
~/.tinyagent/logs/<workspace-uuid>/<session-hash>.jsonl
TINYAGENT_STATE_HOME can override the state root. When a Workspace is copied and its original directory still exists, the copy receives a new UUID. Moving a Workspace preserves its UUID and history. This rule prevents two independent directories from accidentally sharing the same writable state.
Each Run is persisted in this order:
- Save the original user message and create a pending Run before calling the provider.
- Execute the provider request and any tool loop.
- On success, save the Assistant message and commit the completed Run state in the same transaction.
- On failure, retain the user message and failed Run without fabricating an Assistant response.
Failed input remains available for auditing but is not automatically replayed in later provider requests. Tool calls are stored in Assistant messages, and tool results are stored as matching role=tool messages. Replay must preserve valid tool-call boundaries.
Original messages are never deleted by context compaction. Internal summaries and provider-derived messages can be used for model context, but ordinary user history interfaces should distinguish the original conversation from internal representations.
SQLite uses WAL mode. Pending Runs left behind at startup are recovered as failed/interrupted. Before a database schema upgrade, tinyagent creates a backup beside the database. If migration fails, it restores the original database instead of continuing with a partially migrated schema.
Each Session has a JSONL log containing run lifecycle events, execution phases, stable error types, redacted stack locations, and token usage. Logs do not contain API keys, Authorization headers, raw provider responses, or the text of user and Assistant messages.
The CLI provides sessions list/new/resume/delete, while interactive Chat provides /new, /sessions, and /resume. The async and sync agent.sessions SDK interfaces share the same capabilities: list, create, resume, inspect the active Session, delete, and view Messages and Runs.
Sessions manage transactional state and conversation lifecycles. They do not choose the provider context-compaction policy or directly modify long-term Workspace memory. SQLite must remain outside the Agent Workspace, where normal Workspace tools cannot modify it.