Documentation
¶
Overview ¶
Package session implements conversation persistence.
Storage layout mirrors the real Claude Code (src/utils/sessionStorage.ts):
~/.claude/projects/<sanitized-cwd>/<session-id>.jsonl
Each line of the JSONL file is one Entry. On startup we can read any previous session's JSONL and restore its message history, enabling --continue and /resume.
Index ¶
- func ExtractTitle(path string) string
- func FilterUnresolvedToolUses(msgs []api.Message) []api.Message
- func LoadMessages(path string) ([]api.Message, error)
- func LoadTag(path string) (string, error)
- func ProjectDir(cwd, home string) string
- type Activity
- type CostSnapshot
- type Entry
- type FileAccessEntry
- type SearchResult
- type Session
- func (s *Session) Append(entry Entry) error
- func (s *Session) AppendCost(inputTokens, outputTokens int, costUSD float64) error
- func (s *Session) AppendFileAccess(op, path string) error
- func (s *Session) AppendMessage(msg api.Message) error
- func (s *Session) AppendTag(tag string) error
- func (s *Session) LoadMessages() ([]api.Message, error)
- func (s *Session) ReadMode() string
- func (s *Session) SetMode(mode string) error
- func (s *Session) SetSummary(summary string) error
- func (s *Session) SetTitle(title string) error
- func (s *Session) Snapshot() int
- type SessionMeta
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ExtractTitle ¶
ExtractTitle returns the best title for a session: 1. The last custom-title entry if present. 2. The first user message text (truncated to 60 runes). 3. Empty string.
func FilterUnresolvedToolUses ¶
FilterUnresolvedToolUses drops orphan tool_use blocks from assistant messages — i.e. tool_use blocks whose ID has no matching tool_result in any subsequent user message. Anthropic's API rejects history with such orphans; they appear when the stream errors mid-turn before tools could run. Mirrors src/utils/messages.ts filterUnresolvedToolUses.
If filtering empties an assistant message entirely (every block was an orphan tool_use), the message is dropped to avoid sending an empty content array.
func LoadMessages ¶
LoadMessages reads a JSONL transcript at path and returns its messages. Output passes through FilterUnresolvedToolUses so a partial assistant message persisted by conversation recovery (a tool_use with no matching tool_result) doesn't poison the next API call on /resume.
func ProjectDir ¶
New creates a new session rooted at cwd, using sessionID as the file name. ProjectDir returns the directory where session files for cwd are stored.
Types ¶
type Activity ¶
Activity summarizes a session's temporal footprint.
func LoadActivity ¶
LoadActivity walks the JSONL and returns first/last entry timestamps and message count. Mirrors the temporal half of src/utils/sessionActivity.ts — we do not run the heartbeat timer (that's a remote/bridge feature) but we expose enough for /session to display "active for X" / "idle for Y".
type CostSnapshot ¶
type CostSnapshot struct {
InputTokens int `json:"inputTokens"`
OutputTokens int `json:"outputTokens"`
CostUSD float64 `json:"costUSD"`
}
CostSnapshot is the cost entry written to JSONL on each turn.
func LoadCost ¶
func LoadCost(path string) (CostSnapshot, error)
LoadCost reads the last cost entry from a JSONL file. Returns zero CostSnapshot if none found (not an error).
type Entry ¶
type Entry struct {
Type string `json:"type"`
SessionID string `json:"sessionId"`
Timestamp int64 `json:"ts,omitempty"`
Message json.RawMessage `json:"message,omitempty"`
Summary string `json:"summary,omitempty"`
Title string `json:"customTitle,omitempty"`
// Mode is set on type="session_settings" entries to persist session-level
// settings (e.g. "coordinator" or "normal") across resume.
Mode string `json:"mode,omitempty"`
}
Entry is one line in the JSONL transcript file.
type FileAccessEntry ¶
FileAccessEntry records a file read or write.
func LoadFileAccess ¶
func LoadFileAccess(path string) ([]FileAccessEntry, error)
LoadFileAccess reads all file access entries from a JSONL file.
type SearchResult ¶
SearchResult is one matching turn from a transcript search.
type Session ¶
Session manages the JSONL transcript for one conversation.
func FromFile ¶
FromFile wraps an existing JSONL file as a Session so new turns can be appended to it.
func (*Session) AppendCost ¶
AppendCost writes a cost snapshot entry to the session JSONL.
func (*Session) AppendFileAccess ¶
AppendFileAccess records that a file was read or written.
func (*Session) AppendMessage ¶
AppendMessage serializes an api.Message and appends it.
func (*Session) AppendTag ¶
AppendTag persists a tag label for the session. Empty tag clears it. Mirrors src/utils/sessionStorage.ts saveTag — tag entries are appended to the JSONL transcript and the most recent value wins on read.
func (*Session) LoadMessages ¶
LoadMessages reads the JSONL file and returns the message history.
func (*Session) ReadMode ¶
ReadMode scans the session JSONL and returns the most recent mode value from a "session_settings" entry. Returns "" if no mode has been set.
func (*Session) SetMode ¶
SetMode persists a session-level mode setting (e.g. "coordinator" or "normal").
func (*Session) SetSummary ¶
SetSummary persists a compaction summary.
Source Files