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’sString,??/== null,new Date(value)of a JSON value, and V8’s comparator sort. The shared primitives are injsrt.
Structs§
- NewSession
Options - Projected
Entry - One context entry and the messages it contributes after context edits.
- Session
Context SessionContext: what reaches the model.- Session
Info - Session
Manager SessionManager: entries form a tree throughid/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.- Session
Projection SessionProjection: provenance-preserving model context.- Session
Tree getTree()as an arena (deep sessions stay iterative): roots are entries with anull, self-referencing or missing parent; children are ordered by timestamp, oldest first.- System
Env - The real process environment: system clock, OS randomness,
HOME(else/), the process cwd (else/), andULTRON_CODING_AGENT_DIRor~/.ultron/agent. - Tree
Node - A node of
SessionTree;childrenindex intoSessionTree::nodes.
Enums§
- Error
- Errors from session operations.
Invalidmessages are the TypeScript error messages. - Header
Scan Error - Why a bounded header scan stopped without an answer.
- Leaf
- Which leaf a context walk starts from: the TypeScript
leafIdargument.
Constants§
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 (fromfirstKeptEntryId, 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).Nonewhen 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 forcwd, created if missing.- default_
session_ dir_ path getDefaultSessionDirwithout 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.jsonlsession indir, optionally only sessions started incwd. Any directory or stat error makes the lookup unavailable (None).- find_
session_ by_ id SessionManager.findById: the file whose header has exactlyid, without reading bodies.- list_
all_ sessions SessionManager.listAll: every session in a flatsession_dir, or withNonein every project directory under<agent>/sessions; newest activity first.- list_
sessions SessionManager.list: sessions forcwd, 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 toCURRENT_SESSION_VERSIONin 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>/*.jsonlwhose 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).