Crate talos_session

Expand description

Talos session management — append-only session logging with tree-branching support.

Sessions are stored as append-only files, organized by working directory. New sessions use the compact text .tlog format by default; existing .jsonl files are read transparently for backward compatibility. Each line in a session file represents a SessionEntry with fields for id, parent_id, timestamp, role, content, and optional metadata.

§Directory Layout

~/.talos/sessions/
  <project>/
    <uuid>.jsonl

§Branching Model

Each session supports multiple branches. A branch is a linear sequence of entries rooted at a specific entry. The fork method creates a new branch from any existing entry, enabling tree-structured conversations.

§Crash Safety

JSONL is append-only. If a crash occurs, only the last line may be corrupted, which can be detected and skipped during reads.

§Backward Compatibility

Entries without id or parent_id fields (from older JSONL files) are treated as part of a single linear branch. They are assigned synthetic IDs on load.

Re-exports§

pub use sqlite::ForkInfo;
pub use sqlite::IndexError;
pub use sqlite::SearchResult;
pub use sqlite::SessionIndex;
pub use todo::CreateTodo;
pub use todo::TodoAddDependencyTool;
pub use todo::TodoCreateBatchInput;
pub use todo::TodoCreateBatchTool;
pub use todo::TodoCreateInput;
pub use todo::TodoCreateTool;
pub use todo::TodoDeleteInput;
pub use todo::TodoDeleteTool;
pub use todo::TodoDependency;
pub use todo::TodoDependencyInput;
pub use todo::TodoError;
pub use todo::TodoItem;
pub use todo::TodoPriority;
pub use todo::TodoQuery;
pub use todo::TodoQueryInput;
pub use todo::TodoQueryTool;
pub use todo::TodoRemoveDependencyTool;
pub use todo::TodoRepository;
pub use todo::TodoStatus;
pub use todo::TodoUpdate;
pub use todo::TodoUpdateBatchInput;
pub use todo::TodoUpdateBatchTool;
pub use todo::TodoUpdateInput;
pub use todo::TodoUpdateStatusInput;
pub use todo::TodoUpdateStatusTool;
pub use todo::TodoUpdateTool;
pub use todo::status_icon;

Modules§

compaction_engine: Session compaction engine — freezes segments, applies rules, archives (ADR-037 Mechanism B).
sqlite: SQLite-based full-text search index for session messages.
todo: Session-scoped todo storage for orchestration state.

Structs§

CompactTextSessionStore: Compact text session store implementation.
DurableSession: A UUID-backed durable session bound to an opaque host external ID.
DurableTranscriptEntry: One normalized, cursor-addressable durable transcript entry.
JsonlSessionStore: JSONL-based session store implementation.
OrphanSidecarFailure: One reconciliation failure retained without aborting the whole bounded pass.
OrphanSidecarReconciliationPolicy: Safety policy for bounded orphan-sidecar reconciliation.
OrphanSidecarReconciliationReport: Result of scanning Session roots for transcript-less pending SQLite artifacts.
PendingSubmissionRecord: Exact durable record returned for Actor recovery.
PendingSubmissionStore: SQLite sidecar that stores accepted but uncompleted Session work.
PersistencePolicy: Controls what a durable embedded transcript is allowed to retain.
ProviderTerminalDiagnostic
Session: A single session, backed by a JSONL file, with support for tree-branching.
SessionArtifactCleanupReport: Successful deletion details for one Session-owned artifact operation.
SessionBranch: A linear branch within a session.
SessionCapabilities: Format capabilities exposed to embedded hosts.
SessionCleanupCandidate: A session selected by a cleanup policy.
SessionCleanupPolicy: Policy for selecting session cleanup candidates.
SessionCleanupReport: Result of applying a session cleanup policy.
SessionEntry: A single entry in a session branch.
SessionInfo: Information about a session, returned when listing sessions.
SessionManager: Manages sessions on disk.
SessionMetadata: Metadata associated with a session entry.
SessionRuntimeActivation: Immutable logical activation identity.
SessionRuntimeIdentity: Exact declarative model identity owned by one durable Session.
SessionRuntimeState: Current durable Session runtime state.
ToolOutputCompression: Result of applying threshold-based compression to a tool’s output.
TranscriptEntry: A flattened transcript entry suitable for export.
TurnCommit: Result of an idempotent durable turn commit.
TurnTranscriptOutcomeRecord

Enums§

PendingSubmissionError: Failure while reading or mutating pending-submission custody.
ProviderTerminalOutcome
ProviderTerminalSource
SessionError: Errors that can occur during session operations.
SessionRuntimeActivationStatus: Whether a staged activation has crossed the transcript marker barrier.
TurnTranscriptOutcome: Durable proof of the terminal transcript outcome for one runtime Turn.

Constants§

DEFAULT_MAX_ORPHAN_SIDECAR_ENTRIES: Default maximum number of filesystem directory entries inspected in one pass.
DEFAULT_ORPHAN_SIDECAR_MINIMUM_AGE: Default grace period before a transcript-less sidecar can be reconciled.

Traits§

SessionStore: Trait abstracting session entry persistence.

Functions§

compress_tool_output: Compress tool output based on a byte-length threshold.
export_json: Export session entries as a structured JSON array.
export_markdown: Export session entries as a human-readable Markdown transcript.
read_transcript: Read a session file via the given store and return transcript entries.
remove_session_artifacts_for_transcript: Removes the complete Session-owned filesystem set with transcript last.
remove_session_sidecars_for_transcript: Removes WAL, SHM and pending SQLite in that order while retaining the transcript.
remove_session_transcript: Removes only the transcript, the final discoverability commit point.
todo_tool_contributions_for_sessions_dir: Builds the complete session-bound todo tool group for an explicit sessions directory.