Module session 

Session files for production pause/resume.

A SessionFile captures enough agent state to resume a run that terminated abnormally (budget exceeded, stuck, transcript limit). It stores the goal, model, provider, a hash of the tool registry, the steps consumed so far, and the full transcript.

Sessions are written alongside transcripts when --session-out is set and the finish reason is non-success. They live under <workspace>/.recursive/sessions/ by convention.

Split into sub-modules during the Goal 221 module refactor:

• serialize — TranscriptEntry, entry_to_message
• lifecycle — SessionLock, truncate_transcript_to_turn
• orphan — OrphanToolCall
• reader — SessionReader
• writer — SessionWriter, SessionPersistenceSink

Re-exports

pub use lifecycle::truncate_transcript_to_turn;

pub use lifecycle::SessionLock;

pub use lifecycle::SessionLockBusy;

pub use lifecycle::TruncateStats;

pub use orphan::OrphanToolCall;

pub use reader::SessionReader;

pub use serialize::entry_to_message;

pub use serialize::LoadedEntry;

pub use serialize::TranscriptEntry;

pub use writer::SessionPersistenceSink;

pub use writer::SessionWriter;

Modules

lifecycle

Session lifecycle operations: locking, truncation, and UUID chain recovery.

orphan

Orphan tool-call detection types (Goal 153).

reader

Session reader for loading transcripts and metadata from JSONL session files.

serialize

Transcript entry serialization types and conversion to runtime [Message]s.

writer

Session writer for appending messages to JSONL session files and the SessionPersistenceSink event-sink bridge.

Structs

ExportedCompactBoundary

A compaction boundary exported alongside ExportedTranscript::messages.

ExportedTranscript

A portable exported transcript for sharing and analysis.

SessionCost

Cumulative token cost for a session, stored in .meta.json.

SessionFile

A saved session that can be resumed.

SessionMeta

Metadata for a JSONL session.

UsageMeta

Token usage for one or more LLM API calls, as reported by the provider.

Enums

SessionStatus

Status of a session. Persisted as a lowercase string.

Functions

default_session_path

Default session output path for a given workspace. Returns ~/.recursive/workspaces/<ws-hash>/sessions/<timestamp>-<goal-prefix>.json.

hash_tool_specs

Compute a BLAKE3 hash of the tool registry specs.

list_sessions

List all session files in a workspace’s session directory.