Skip to main content

Crate session_file

Crate session_file 

Source
Expand description

Ultron’s session persistence format: the Pi session JSONL written by the TypeScript SessionManager (packages/coding-agent/src/core/session-manager.ts).

A session file is one JSON value per line: a session header (version 3), then entries that form a tree through id/parentId. Files from versions 1 and 2 are migrated and rewritten on load. Lines are written exactly as JSON.stringify writes them, so files stay byte-compatible with the TypeScript implementation in both directions.

Entries are kept as JSON values rather than typed structs: unknown fields and entry types from newer or older writers survive a load/rewrite unchanged.

Modules§

js
JavaScript semantics only the session format uses: Array.prototype.join’s String, ?? /== null, new Date(value) of a JSON value, and V8’s comparator sort. The shared primitives are in jsrt.

Structs§

NewSessionOptions
ProjectedEntry
One context entry and the messages it contributes after context edits.
SessionContext
SessionContext: what reaches the model.
SessionInfo
SessionManager
SessionManager: entries form a tree through id/parentId; the leaf is the current position. Appends add a child of the leaf; branching moves the leaf. Persisted sessions are written only once the first assistant message exists, then appended line by line.
SessionProjection
SessionProjection: provenance-preserving model context.
SessionTree
getTree() as an arena (deep sessions stay iterative): roots are entries with a null, self-referencing or missing parent; children are ordered by timestamp, oldest first.
SystemEnv
The real process environment: system clock, OS randomness, HOME (else /), the process cwd (else /), and ULTRON_CODING_AGENT_DIR or ~/.ultron/agent.
TreeNode
A node of SessionTree; children index into SessionTree::nodes.

Enums§

Error
Errors from session operations. Invalid messages are the TypeScript error messages.
HeaderScanError
Why a bounded header scan stopped without an answer.
Leaf
Which leaf a context walk starts from: the TypeScript leafId argument.

Constants§

CURRENT_SESSION_VERSION

Traits§

Env
Inputs the TypeScript implementation takes from the process (Date, crypto, the agent dir).

Functions§

build_context_entries
buildContextEntries: the active path with the latest compaction first, then the entries it kept (from firstKeptEntryId, without system messages), then everything after it.
build_session_context
build_session_projection
current_system_message
getCurrentSystemMessage: every system message replayed into one (content appended, sections patched by name, tools resolved). None when there is no system state.
current_tools
getCurrentTools: tools after replaying every system message’s removals and additions.
default_session_dir
getDefaultSessionDir: the default session directory for cwd, created if missing.
default_session_dir_path
getDefaultSessionDir without creating it: <agent>/sessions/<encoded resolved cwd>.
entry_messages
sessionEntryToContextMessages: the messages one entry contributes to model context.
find_most_recent_session
findMostRecentSession: the most recently modified .jsonl session in dir, optionally only sessions started in cwd. Any directory or stat error makes the lookup unavailable (None).
find_session_by_id
SessionManager.findById: the file whose header has exactly id, without reading bodies.
list_all_sessions
SessionManager.listAll: every session in a flat session_dir, or with None in every project directory under <agent>/sessions; newest activity first.
list_sessions
SessionManager.list: sessions for cwd, newest activity first.
load_entries_from_file
loadEntriesFromFile: all parsed lines of a session file, or nothing when the first parsed line is not a session header. A missing file is empty. When the file is a session whose last line lacks a newline, a newline is appended so the next append starts a new line.
migrate_session_entries
migrateToCurrentVersion: brings entries to CURRENT_SESSION_VERSION in place. The version comes from the first header (absent: 1). Returns whether anything ran.
migrate_sessions_from_agent_root
migrateSessionsFromAgentRoot (src/migrations.ts): v0.30.0 wrote sessions straight into the agent dir; move each <agent>/*.jsonl whose first line is a header with a cwd into that cwd’s session dir. Files that do not qualify, or whose target exists, stay where they are.
parse_session_entries
parseSessionEntries: every non-blank line that parses as JSON (malformed lines are skipped).
read_session_header
readSessionHeader: the header from the first parsed line, reading at most [MAX_SESSION_HEADER_SCAN_BYTES] (plus one byte to tell a file that ends there from a longer one).