threecode/session

Search:
Group by:

Session persistence in the human-readable .3log format.

.3log is an append-friendly, diff-friendly flat-text format. Each record is a header line (role and space-separated args) followed by body lines indented two spaces. The format is both the on-disk representation and the session audit trail - readable without tooling and diffable in git.

The system prompt is intentionally omitted on save: it is rebuilt from the profile on every resume, saving several KB per session and ensuring the prompt is always current (not a stale snapshot from when the session started).

On load, the full OpenAI-shape messages JsonNode array is reconstructed from the records so the session can be resumed mid-conversation with no loss.

Types

SessionLocked = object of CatchableError
SessionPreview = object
  cwd*: string
  profile*: string
  msgCount*: int
  firstUser*: string

Consts

SessionExt = ".3log"

Procs

proc acquireSessionLock(path: string) {....raises: [IOError, SessionLocked], tags: [
    ReadEnvEffect, ReadIOEffect, WriteDirEffect, ReadDirEffect, TimeEffect],
                                        forbids: [].}

Atomically claim the lock for path.

If a lock exists but its owner process is no longer alive, it's treated as stale (left behind by a crash) and removed automatically, then acquisition retries once. Raises SessionLocked only when another live 3code process genuinely holds the lock (or a second racer grabbed it in the retry window).

proc appendIndexAt(indexDir, cwd, id: string) {....raises: [],
    tags: [WriteDirEffect, ReadDirEffect, WriteIOEffect], forbids: [].}
Append id to the cwd's index file. Silent on failure: a missing index entry only means the session won't show in resume-latest, never a crash.
proc appendSessionIndex(cwd, id: string) {....raises: [], tags: [WriteDirEffect,
    ReadDirEffect, WriteIOEffect, ReadEnvEffect, ReadIOEffect], forbids: [].}
proc clearDraft(session: Session) {....raises: [], tags: [ReadDirEffect,
    WriteDirEffect, ReadEnvEffect, ReadIOEffect], forbids: [].}
Remove the prompt draft sidecar(s). Called when a prompt is committed so a clean exit doesn't leave a stale draft. Removes both scopes — whichever was active at submit time — so this is correct regardless of pre/post-first-turn state. Cheap and a no-op when neither exists.
proc clearPendingDraft(cwd: string) {....raises: [], tags: [ReadDirEffect,
    WriteDirEffect, ReadEnvEffect, ReadIOEffect], forbids: [].}
Remove the cwd-keyed pending prompt draft for cwd. No-op when none exists.
proc currentDraftPath(session: Session): string {....raises: [],
    tags: [ReadDirEffect, ReadEnvEffect, ReadIOEffect], forbids: [].}
The draft path for the live session: id-keyed once a .3log exists (post-first-turn), otherwise the cwd-keyed pending path. This is the single decision point for which scope a draft lives in.
proc draftDir(): string {....raises: [], tags: [ReadEnvEffect, ReadIOEffect],
                          forbids: [].}
proc draftPathFor(sessionPath: string): string {....raises: [],
    tags: [ReadEnvEffect, ReadIOEffect], forbids: [].}
proc firstUserMessage(messages: JsonNode): string {....raises: [],
    tags: [RootEffect], forbids: [].}
proc historyFile(): string {....raises: [], tags: [ReadEnvEffect, ReadIOEffect,
    WriteDirEffect, ReadDirEffect], forbids: [].}
proc indexIdsAt(indexDir, cwd: string): seq[string] {....raises: [],
    tags: [ReadIOEffect], forbids: [].}
Session ids for cwd, latest-first. Reads the single small index file (one line per session) — never touches a .3log.
proc indexPathAt(indexDir, cwd: string): string {....raises: [], tags: [],
    forbids: [].}
proc listSessionPaths(): seq[string] {....raises: [OSError], tags: [ReadEnvEffect,
    ReadIOEffect, ReadDirEffect], forbids: [].}
proc listSessionPathsForCwd(cwd: string): seq[string] {....raises: [],
    tags: [ReadIOEffect, ReadEnvEffect, ReadDirEffect], forbids: [].}
Sessions saved under cwd, latest-first — read straight from the cwd index, so it never parses a .3log. A missing/stale index entry is skipped via the fileExists check (e.g. a session deleted on disk).
proc loadDraft(sessionPath: string): string {....raises: [],
    tags: [ReadEnvEffect, ReadIOEffect, ReadDirEffect], forbids: [].}
Read the session-id-keyed prompt draft for sessionPath, or "" if there is none or it is unreadable. Used by resume (post-first-turn drafts). The empty string is indistinguishable from absence, which is fine: an empty draft restores to an empty editor.
proc loadPendingDraft(cwd: string): string {....raises: [],
    tags: [ReadEnvEffect, ReadIOEffect, ReadDirEffect], forbids: [].}
Read the cwd-keyed pending prompt draft for cwd, or "" if there is none or it is unreadable. Used to restore an unsent prompt from a previous, killed-before-first-turn run when starting a fresh session in the same directory.
proc loadSessionFile(path: string): (Session, JsonNode) {.
    ...raises: [IOError, KeyError],
    tags: [ReadIOEffect, WriteIOEffect, RootEffect], forbids: [].}
proc mangleCwd(cwd: string): string {....raises: [], tags: [], forbids: [].}
proc newSessionPath(): string {....raises: [], tags: [TimeEffect, ReadEnvEffect,
    ReadIOEffect], forbids: [].}
proc pendingDraftDir(): string {....raises: [],
                                 tags: [ReadEnvEffect, ReadIOEffect],
                                 forbids: [].}
proc pendingDraftPathFor(cwd: string): string {....raises: [],
    tags: [ReadEnvEffect, ReadIOEffect], forbids: [].}
The pre-first-turn draft for a working directory. Keyed by the collision-free mangled cwd (same scheme as the cwd session index) so distinct directories never share a draft. One per directory: a singleton, overwritten as the user edits.
proc previewSession(path: string): SessionPreview {....raises: [KeyError],
    tags: [ReadIOEffect], forbids: [].}
Fast peek for --list and :sessions — reads the file, parses just enough to show cwd / profile / count / first user line. Doesn't reconstruct the full message tree.
proc releaseActiveSessionLock() {....raises: [], tags: [WriteDirEffect],
                                  forbids: [].}
proc releaseSessionLock(path: string) {....raises: [], tags: [ReadEnvEffect,
    ReadIOEffect, WriteDirEffect], forbids: [].}
proc renderSession(session: Session; messages: JsonNode): string {....raises: [],
    tags: [RootEffect, ReadIOEffect, WriteIOEffect], forbids: [].}
proc resolveSessionPath(id: string; cwd = ""): string {....raises: [OSError],
    tags: [ReadIOEffect, ReadEnvEffect, ReadDirEffect], forbids: [].}
id is bare (no extension) or a full path. Returns "" if not found. When id is empty and cwd is set, returns the latest session for that cwd via the cwd index (no session parsed); with cwd unset, the latest of any via a plain directory listing.
proc saveDraft(session: Session; text: string) {....raises: [Exception, IOError], tags: [
    ReadDirEffect, ReadEnvEffect, ReadIOEffect, WriteDirEffect, WriteIOEffect],
    forbids: [].}
Persist the current prompt-editor text as an atomic draft sidecar so an unexpected shutdown never loses a half-typed prompt. Writes to whichever scope currentDraftPath picks (cwd-keyed pending before the first turn, session-id-keyed after). A blank draft removes the sidecar rather than leaving an empty file, so an idle editor produces no draft. No-op without a cwd to key on (and no savePath).
proc saveSession(session: Session; messages: JsonNode) {....raises: [IOError], tags: [
    ReadDirEffect, WriteDirEffect, WriteIOEffect, RootEffect, ReadIOEffect,
    ReadEnvEffect], forbids: [].}
proc sessionDir(): string {....raises: [], tags: [ReadEnvEffect, ReadIOEffect],
                            forbids: [].}
proc sessionIdFromPath(path: string): string {....raises: [], tags: [], forbids: [].}
proc sessionLockDir(): string {....raises: [], tags: [ReadEnvEffect, ReadIOEffect],
                                forbids: [].}
proc sessionLockPathFor(path: string): string {....raises: [],
    tags: [ReadEnvEffect, ReadIOEffect], forbids: [].}
proc sessionPathIndexDir(): string {....raises: [],
                                     tags: [ReadEnvEffect, ReadIOEffect],
                                     forbids: [].}
proc usageFromJson(j: JsonNode): Usage {....raises: [], tags: [RootEffect],
    forbids: [].}