session

Documentation

Overview

Package session manages conversation persistence as tree-structured JSONL files. Each session is a single file with entries linked by ID/ParentID, enabling in-place branching without creating new files.

Design draws from pi-mono's session format: https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/session.md

Index

• type BranchSummaryData
• type CustomMessageData
• type Entry
• type EntryInfo
• type LabelData
• type Meta
• type Session
  • func New(dir, cwd string) (*Session, error)
  • func Open(path string) (*Session, error)
  • func (s *Session) Append(msg core.Message) error
  • func (s *Session) AppendCompact(msgs []core.Message, tokensBefore int) error
  • func (s *Session) AppendCustom(kind string, data any) error
  • func (s *Session) AppendCustomMessage(role, content string) error
  • func (s *Session) AppendLabel(targetID, label string) error
  • func (s *Session) Branch(entryID string) error
  • func (s *Session) BranchWithSummary(entryID, summary string) error
  • func (s *Session) Close() error
  • func (s *Session) EntryInfos() []EntryInfo
  • func (s *Session) Fork(keepMessages int) (*Session, error)
  • func (s *Session) FullTree() []TreeNode
  • func (s *Session) ID() string
  • func (s *Session) Label(entryID string) string
  • func (s *Session) LeafID() string
  • func (s *Session) Messages() []core.Message
  • func (s *Session) Meta() Meta
  • func (s *Session) Path() string
  • func (s *Session) ResetLeaf() error
  • func (s *Session) SetModel(model string) error
  • func (s *Session) SetTitle(title string) error
• type Summary
  • func List(dir string) ([]Summary, error)
• type TreeNode

Types

type BranchSummaryData

type BranchSummaryData struct {
	Summary string `json:"summary"`
	FromID  string `json:"fromId"` // leaf ID of the abandoned branch
}

BranchSummaryData holds the data payload for a branch_summary entry.

type CustomMessageData

type CustomMessageData struct {
	Role    string `json:"role"` // "user" or "assistant"
	Content string `json:"content"`
}

CustomMessageData holds the data payload for a custom_message entry.

type Entry

type Entry struct {
	Type         string          `json:"type"`               // "user", "assistant", "tool_result", "meta", "compact", "branch_summary"
	ID           string          `json:"id,omitempty"`       // 8-char hex; empty for meta and legacy entries
	ParentID     string          `json:"parentId,omitempty"` // parent entry ID; empty for first entry
	Timestamp    time.Time       `json:"ts"`
	Data         json.RawMessage `json:"data"`
	TokensBefore int             `json:"tokensBefore,omitempty"` // tokens in context before compaction; only set on compact entries
}

Entry is a single line in the JSONL session file.

type EntryInfo

type EntryInfo struct {
	ID        string
	ParentID  string
	Type      string
	Timestamp time.Time
	Children  int
}

EntryInfo is a public view of a tree node for display and navigation.

type LabelData

type LabelData struct {
	TargetID string `json:"targetId"` // entry ID being labeled
	Label    string `json:"label"`    // empty = clear label
}

LabelData holds the data payload for a label entry.

type Meta

type Meta struct {
	ID        string    `json:"id"`
	CWD       string    `json:"cwd"`
	Model     string    `json:"model,omitempty"`
	CreatedAt time.Time `json:"createdAt"`
	Title     string    `json:"title,omitempty"`
	ParentID  string    `json:"parentId,omitzero"`
	ForkPoint int       `json:"forkPoint,omitzero"`
}

Meta holds session metadata.

type Session

type Session struct {
	// contains filtered or unexported fields
}

Session manages a single conversation as a tree-structured JSONL file. Entries form a tree via ID/ParentID linking. A leaf pointer tracks the current position; Messages() walks from leaf to root to build the active branch.

func New

func New(dir, cwd string) (*Session, error)

New creates a new session in the given directory.

func Open

func Open(path string) (*Session, error)

Open loads an existing session from a JSONL file. Legacy sessions (entries without IDs) are transparently upgraded in memory.

func (*Session) Append

func (s *Session) Append(msg core.Message) error

Append adds a message to the session at the current leaf and persists it.

func (*Session) AppendCompact

func (s *Session) AppendCompact(msgs []core.Message, tokensBefore int) error

AppendCompact writes a compact checkpoint at the current leaf. On context build, all ancestor messages before this entry are replaced by the compacted messages. tokensBefore is the token count in context immediately before compaction (0 = unknown).

func (*Session) AppendCustom

func (s *Session) AppendCustom(kind string, data any) error

AppendCustom writes a custom extension entry to the session at the current leaf. The kind should be namespaced (e.g., "ext:memory:facts"). Data is JSON-marshaled. Custom entries are stored in the tree but do not appear in Messages().

func (*Session) AppendCustomMessage

func (s *Session) AppendCustomMessage(role, content string) error

AppendCustomMessage writes a message entry that persists AND appears in Messages(). Role must be "user" or "assistant". Used by extensions to inject durable context annotations.

func (*Session) AppendLabel

func (s *Session) AppendLabel(targetID, label string) error

AppendLabel writes a label entry targeting a specific entry ID. The label is stored in the labels map (last-write-wins per target). Empty label clears an existing label.

func (*Session) Branch

func (s *Session) Branch(entryID string) error

Branch moves the leaf to an earlier entry, creating an in-place branch point. A branch_summary entry is written to persist the new leaf position across reloads.

func (*Session) BranchWithSummary

func (s *Session) BranchWithSummary(entryID, summary string) error

BranchWithSummary moves the leaf to an earlier entry and writes a branch_summary entry capturing context about the abandoned branch. The summary entry becomes the new leaf.

func (*Session) Close

func (s *Session) Close() error

Close closes the session file.

func (*Session) EntryInfos

func (s *Session) EntryInfos() []EntryInfo

EntryInfos returns info about all entries on the current branch (root to leaf).

func (*Session) Fork

func (s *Session) Fork(keepMessages int) (*Session, error)

Fork creates a new session file with messages from the current branch. keepMessages limits how many messages to copy (0 = all).

func (*Session) FullTree

func (s *Session) FullTree() []TreeNode

FullTree returns every entry in the session as a flat list ordered by DFS traversal. Active path entries are marked. Children are sorted with the active subtree first, then by timestamp (oldest first).

func (*Session) ID

func (s *Session) ID() string

ID returns the session ID.

func (*Session) Label

func (s *Session) Label(entryID string) string

Label returns the label for an entry, or empty string.

func (*Session) LeafID

func (s *Session) LeafID() string

LeafID returns the current leaf entry ID.

func (*Session) Messages

func (s *Session) Messages() []core.Message

Messages returns all messages on the current branch (leaf to root walk).

func (*Session) Meta

func (s *Session) Meta() Meta

Meta returns session metadata.

func (*Session) Path

func (s *Session) Path() string

Path returns the session file path.

func (*Session) ResetLeaf

func (s *Session) ResetLeaf() error

ResetLeaf writes a branch_summary entry with no parent and moves the leaf to it. After reset, Messages() returns an empty slice — the next Append starts a new trunk as a sibling of the existing root.

func (*Session) SetModel

func (s *Session) SetModel(model string) error

SetModel updates the model in metadata.

func (*Session) SetTitle

func (s *Session) SetTitle(title string) error

SetTitle updates the session title.

type Summary

type Summary struct {
	ID        string    `json:"id"`
	Path      string    `json:"path"`
	Title     string    `json:"title"`
	Model     string    `json:"model"`
	CWD       string    `json:"cwd"`
	CreatedAt time.Time `json:"createdAt"`
	Messages  int       `json:"messages"`
	ParentID  string    `json:"parentId,omitzero"`
}

Summary is returned by List.

func List

func List(dir string) ([]Summary, error)

List returns summaries of all sessions in a directory, newest first.

type TreeNode

type TreeNode struct {
	ID           string
	ParentID     string
	Type         string
	Timestamp    time.Time
	Children     int
	OnActivePath bool
	Depth        int
	Preview      string // truncated content for user messages
	Label        string // user-assigned bookmark label (empty if none)
	TokensBefore int    // tokens in context before compaction; only set on compact entries (0 = absent)
}

TreeNode is a full-tree view of a session entry for DAG rendering.