Session class final

A session: an append-only tree of records with an active leaf.

Ported from pi's Session class. All reads go through the storage's in-memory index; all writes append to the underlying JSONL file.

Constructors

Session(SessionStorage _storage)

Creates a Session over storage.

const

Properties

hashCode → int

The hash code for this object.

no setter, inherited

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

Methods

appendActiveToolsChange(List<String> activeToolNames) → Future<String>

Appends an active-tools change. Returns the new record id.

appendCheckpoint({required int messageCount, String? goal}) → Future<String>

Appends a checkpoint mark for the checkpoint/rewind tools. Returns the new record id — the rewind uses it as the session-tree branch anchor. See CheckpointRecord.

appendCompaction({required String summary, required String firstKeptEntryId, required int tokensBefore, Object? details, bool? fromHook}) → Future<String>

Appends a compaction record. Returns the new record id.

appendCustomEntry({required String customType, Object? data}) → Future<String>

Appends an application-defined record that stays out of model context. Returns the new record id.

appendCustomMessageEntry({required String customType, required Object content, required bool display, Object? details}) → Future<String>

Appends an application-defined record that projects into model context as a user message. content is a String or a List<ContentBlock>. Returns the new record id.

appendLabel(String targetId, String? label) → Future<String>

Attaches (or removes, when label is null) a label to targetId. Returns the new record id.

appendMessage(Message message) → Future<String>

Appends a conversation message at the active leaf. Returns the new record id.

appendModelChange({required String provider, required String modelId}) → Future<String>

Appends a model change. Returns the new record id.

appendSessionName(String name) → Future<String>

Sets the session display name (newlines are sanitized away).

appendThinkingLevelChange(String thinkingLevel) → Future<String>

Appends a thinking-level change. Returns the new record id.

buildContext() → Future<SessionContext>

Rebuilds the full SessionContext (messages plus derived model state) for the active branch.

buildContextMessages() → Future<List<Message>>

Rebuilds the model context from the active branch: messages in branch order, with compaction, branch-summary, and custom-message records projected per pi's buildSessionContext + convertToLlm.

getBranch({String? fromId}) → Future<List<SessionRecord>>

The records of the active branch (or of the branch ending at fromId), root-first.

getChildren(String? parentId) → Future<List<SessionRecord>>

The direct children of parentId (roots when null), in file order.

getEntries() → Future<List<SessionRecord>>

All records in file order.

getEntry(String id) → Future<SessionRecord?>

Looks up a record by id.

getLabel(String id) → Future<String?>

The current label attached to record id, if any.

getLeafId() → Future<String?>

The id of the active leaf record, or null at the tree root.

getMetadata() → Future<SessionMetadata>

The session metadata (from the file header).

getSessionName() → Future<String?>

The session's display name (last session_info record wins).

getStorage() → SessionStorage

The underlying storage.

moveTo(String? entryId, {String? summary, Object? details, bool? fromHook}) → Future<String?>

Moves the active leaf to entryId (or the tree root when null), appending a leaf record. When summary is provided, also appends a branch_summary record and returns its id; otherwise returns null.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

toString() → String

A string representation of this object.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited