session

package
v0.124.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 8, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Index

Constants

View Source
const BareSessionKey = "__bare__"

BareSessionKey is the sentinel passed in place of a working directory when Kit runs in bare mode. Bare sessions are not tied to a working directory — that is the point of the mode — so they all share one bucket and `--continue` resumes the last bare conversation from anywhere.

DefaultSessionDir maps this sentinel to a directory that sits beside the cwd-keyed namespace rather than inside it, so no working directory can ever resolve to the bare bucket. See the comment there.

View Source
const CurrentVersion = 3

CurrentVersion is the session format version for JSONL tree sessions.

Variables

View Source
var ErrUnknownEntryType = errors.New("unknown entry type")

ErrUnknownEntryType is returned by UnmarshalEntry when a line is valid JSON but carries an entry type this build does not know. Callers must not treat it as corruption of the transcript: the line is complete and was written by a newer version of kit.

Functions

func DefaultSessionDir

func DefaultSessionDir(cwd string) string

DefaultSessionDir returns the default session storage directory for a cwd. Convention: ~/.kit/sessions/<encoded-cwd>, where path separators are encoded as "--" with no leading or trailing dashes — e.g. /home/user/proj becomes home--user--proj. See encodeCwdForDir for the full encoding rules (including Windows path handling).

The bare sentinel is special-cased to ~/.kit/bare-sessions. The encoding is lossy — "/__bare__" and "__bare__" both encode to "__bare__" — so routing bare sessions through it would let a project directory named /__bare__ share the bare bucket and have `--continue` resume the wrong conversation. Matching on the raw sentinel before encoding keeps the two namespaces apart: a real /__bare__ directory still gets ~/.kit/sessions/__bare__.

func DeleteSession

func DeleteSession(path string) error

DeleteSession removes a session file from disk.

func FindSessionPathByID added in v0.85.0

func FindSessionPathByID(cwd, id string) (string, error)

FindSessionPathByID locates the JSONL session file whose header ID matches the given session UUID. The session directory for cwd is searched first (the common case for subagent sessions, which live alongside the parent's sessions), then all session directories under ~/.kit/sessions, and finally the bare bucket. Only file headers (first line) are read, so the scan is cheap even with many sessions. Returns an error when no session with that ID exists.

func GenerateEntryID

func GenerateEntryID() string

GenerateEntryID creates a unique entry identifier (16 hex chars).

func GenerateSessionID

func GenerateSessionID() string

GenerateSessionID creates a unique session identifier (32 hex chars).

func MarshalEntry

func MarshalEntry(entry any) ([]byte, error)

MarshalEntry serializes any entry to a JSON line (no trailing newline).

func UnmarshalEntry

func UnmarshalEntry(data []byte) (any, error)

UnmarshalEntry deserializes a JSON line into the appropriate entry type. Returns one of: *SessionHeader, *MessageEntry, *ModelChangeEntry, *BranchSummaryEntry, *LabelEntry, *SessionInfoEntry.

Types

type BranchSummaryEntry

type BranchSummaryEntry struct {
	Entry
	FromID  string `json:"from_id"` // leaf of the summarized branch
	Summary string `json:"summary"`
}

BranchSummaryEntry provides LLM-generated context from an abandoned branch. When the user navigates away from a branch, a summary of that branch's conversation is stored so the LLM retains context about what was explored.

func NewBranchSummaryEntry

func NewBranchSummaryEntry(parentID, fromID, summary string) *BranchSummaryEntry

NewBranchSummaryEntry creates a BranchSummaryEntry.

type CompactionEntry added in v0.19.0

type CompactionEntry struct {
	Entry
	Summary          string   `json:"summary"`
	FirstKeptEntryID string   `json:"first_kept_entry_id"`
	TokensBefore     int      `json:"tokens_before"`
	TokensAfter      int      `json:"tokens_after"`
	MessagesRemoved  int      `json:"messages_removed"`
	ReadFiles        []string `json:"read_files,omitempty"`
	ModifiedFiles    []string `json:"modified_files,omitempty"`
}

CompactionEntry records an LLM-generated summary of older messages. Instead of deleting old messages, the tree manager skips entries before FirstKeptEntryID when building the LLM context, preserving full history.

func NewCompactionEntry added in v0.19.0

func NewCompactionEntry(parentID, summary, firstKeptEntryID string, tokensBefore, tokensAfter, messagesRemoved int, readFiles, modifiedFiles []string) *CompactionEntry

NewCompactionEntry creates a CompactionEntry.

type Entry

type Entry struct {
	Type      EntryType `json:"type"`
	ID        string    `json:"id"`
	ParentID  string    `json:"parent_id,omitempty"`
	Timestamp time.Time `json:"timestamp"`
}

Entry is the common structure shared by all tree entries (everything except the session header). Every entry has an ID, an optional ParentID (empty for root entries), a type tag, and a timestamp.

func NewEntry

func NewEntry(entryType EntryType, parentID string) Entry

NewEntry creates a base Entry with a generated ID and current timestamp.

type EntryType

type EntryType string

EntryType identifies the kind of entry stored in a JSONL session file. Sessions are append-only JSONL files where each line is a typed entry linked by id/parent_id to form a tree structure.

const (
	EntryTypeSession          EntryType = "session"
	EntryTypeMessage          EntryType = "message"
	EntryTypeIncompleteOutput EntryType = "incomplete_output"
	EntryTypeModelChange      EntryType = "model_change"
	EntryTypeBranchSummary    EntryType = "branch_summary"
	EntryTypeLabel            EntryType = "label"
	EntryTypeSessionInfo      EntryType = "session_info"
	EntryTypeExtensionData    EntryType = "extension_data"
	EntryTypeCompaction       EntryType = "compaction"
	EntryTypeSystemPrompt     EntryType = "system_prompt"
)

type ExtensionDataEntry added in v0.3.0

type ExtensionDataEntry struct {
	Entry
	ExtType string `json:"ext_type"` // Extension-defined type string (e.g. "plan-mode:state")
	Data    string `json:"data"`     // Extension-defined data (JSON or plain text)
}

ExtensionDataEntry stores custom extension data in the session tree. Extensions use this to persist state that survives across session restarts.

func NewExtensionDataEntry added in v0.3.0

func NewExtensionDataEntry(parentID, extType, data string) *ExtensionDataEntry

NewExtensionDataEntry creates an ExtensionDataEntry.

type IncompleteOutputEntry added in v0.121.0

type IncompleteOutputEntry struct {
	Entry
	AttemptID  string `json:"attempt_id"`
	Text       string `json:"text"`
	Incomplete bool   `json:"incomplete"`
}

IncompleteOutputEntry stores unfinished text outside normal model history.

type LabelEntry

type LabelEntry struct {
	Entry
	TargetID string `json:"target_id"`
	Label    string `json:"label"`
}

LabelEntry bookmarks a specific entry with a user-defined label.

func NewLabelEntry

func NewLabelEntry(parentID, targetID, label string) *LabelEntry

NewLabelEntry creates a LabelEntry.

type MessageEntry

type MessageEntry struct {
	Entry
	Role     string          `json:"role"`
	Parts    json.RawMessage `json:"parts"` // type-tagged parts array
	Model    string          `json:"model,omitempty"`
	Provider string          `json:"provider,omitempty"`
}

MessageEntry stores a conversation message as a tree entry. The message content uses the same type-tagged parts format as the existing session persistence layer, enabling reuse of MarshalParts/UnmarshalParts.

func NewMessageEntry

func NewMessageEntry(parentID string, msg message.Message) (*MessageEntry, error)

NewMessageEntry creates a MessageEntry from a message.Message, linking it to the given parent entry in the tree.

func (*MessageEntry) Text added in v0.94.0

func (e *MessageEntry) Text() string

Text returns the plain-text content of the message, concatenating every text part with newlines. Non-text parts (tool calls, tool results, images, reasoning) are ignored, so a tool-only message yields an empty string.

This is a cheap projection intended for previews and list rendering: it scans the type-tagged parts directly instead of going through ToMessage, and it never fails — malformed parts simply yield an empty string.

func (*MessageEntry) ToMessage

func (e *MessageEntry) ToMessage() (message.Message, error)

ToMessage converts a MessageEntry back to a message.Message by unmarshaling the type-tagged parts.

type ModelChangeEntry

type ModelChangeEntry struct {
	Entry
	Provider string `json:"provider"`
	ModelID  string `json:"model_id"`
}

ModelChangeEntry records a provider/model switch in the session tree.

func NewModelChangeEntry

func NewModelChangeEntry(parentID, provider, modelID string) *ModelChangeEntry

NewModelChangeEntry creates a ModelChangeEntry.

type SessionHeader

type SessionHeader struct {
	Type          EntryType `json:"type"`                     // always "session"
	Version       int       `json:"version"`                  // format version (3)
	ID            string    `json:"id"`                       // session UUID
	Timestamp     time.Time `json:"timestamp"`                // creation time
	Cwd           string    `json:"cwd"`                      // working directory
	ParentSession string    `json:"parent_session,omitempty"` // path to parent if forked

	// Subagent fields (set when session is created by a subagent)
	ParentSessionID string `json:"parent_session_id,omitempty"` // UUID of parent session
	SubagentTask    string `json:"subagent_task,omitempty"`     // original task prompt
}

SessionHeader is the first line in a JSONL session file. It carries metadata about the session and does NOT participate in the tree structure (it has no ID or ParentID).

type SessionInfo

type SessionInfo struct {
	// Path is the absolute path to the JSONL session file.
	Path string

	// ID is the session UUID from the header.
	ID string

	// Cwd is the working directory the session was created in.
	Cwd string

	// Name is the user-defined display name (from session_info entries).
	Name string

	// ParentSessionPath is the parent session path if this session was forked.
	ParentSessionPath string

	// ParentSessionID is the UUID of the parent session (for subagent sessions).
	ParentSessionID string

	// SubagentTask is the original task prompt (for subagent sessions).
	SubagentTask string

	// Created is when the session was first created.
	Created time.Time

	// Modified is the timestamp of the last activity (latest message).
	Modified time.Time

	// MessageCount is the number of message entries in the session.
	MessageCount int

	// FirstMessage is a preview of the first user message.
	FirstMessage string
}

SessionInfo contains metadata about a discovered session, used for listing and session picker display.

func ListAllSessions

func ListAllSessions() ([]SessionInfo, error)

ListAllSessions finds all sessions across all working directories, sorted by modification time (newest first).

func ListSessions

func ListSessions(cwd string) ([]SessionInfo, error)

ListSessions finds all sessions for a given working directory, sorted by modification time (newest first).

type SessionInfoEntry

type SessionInfoEntry struct {
	Entry
	Name string `json:"name"`
}

SessionInfoEntry stores a user-defined display name for the session.

func NewSessionInfoEntry

func NewSessionInfoEntry(parentID, name string) *SessionInfoEntry

NewSessionInfoEntry creates a SessionInfoEntry.

type SystemPromptEntry added in v0.40.0

type SystemPromptEntry struct {
	Type      EntryType `json:"type"`      // always "system_prompt"
	ID        string    `json:"id"`        // unique entry ID
	Timestamp time.Time `json:"timestamp"` // when captured
	Content   string    `json:"content"`   // the system prompt text
	Model     string    `json:"model"`     // the model used (e.g., "claude-sonnet-4-5")
	Provider  string    `json:"provider"`  // the provider used (e.g., "anthropic")
}

SystemPromptEntry records the system prompt and model used for the session. This is primarily for sharing/debugging to see what instructions were active during the conversation. It does NOT participate in the tree structure (no ParentID) and is not used when building LLM context.

func NewSystemPromptEntry added in v0.40.0

func NewSystemPromptEntry(content, model, provider string) *SystemPromptEntry

NewSystemPromptEntry creates a SystemPromptEntry.

type TreeManager

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

TreeManager manages a tree-structured JSONL session. It is the replacement for the linear session.Manager:

  • JSONL append-only format (one JSON object per line)
  • Tree structure via id/parent_id on every entry
  • Leaf pointer tracking current position
  • Context building walks from leaf to root
  • Auto-discovery by working directory

func ContinueRecent

func ContinueRecent(cwd string) (*TreeManager, error)

ContinueRecent finds the most recently modified session for the given cwd, or creates a new one if none exists.

func CreateTreeSession

func CreateTreeSession(cwd string) (*TreeManager, error)

CreateTreeSession creates a new tree session persisted at the default location for the given working directory.

func InMemoryTreeSession

func InMemoryTreeSession(cwd string) *TreeManager

InMemoryTreeSession creates a tree session that is not persisted to disk.

func OpenTreeSession

func OpenTreeSession(path string) (*TreeManager, error)

OpenTreeSession opens an existing JSONL session file.

The session file is locked for exclusive use before anything is read, so two processes cannot load the same transcript and then append to it concurrently. Reopening finishes with a repair pass: tool calls left unanswered by a stopped process get synthetic results, so the session is resumable (see repair.go).

func (*TreeManager) AppendBranchSummary

func (tm *TreeManager) AppendBranchSummary(fromID, summary string) (string, error)

AppendBranchSummary adds a summary of an abandoned branch.

func (*TreeManager) AppendCompaction added in v0.19.0

func (tm *TreeManager) AppendCompaction(summary, firstKeptEntryID string, tokensBefore, tokensAfter, messagesRemoved int, readFiles, modifiedFiles []string) (string, error)

AppendCompaction adds a compaction entry to the tree. The entry records the summary and the ID of the first entry that should be preserved in the LLM context. Messages before that entry are replaced by the summary.

The compaction entry becomes a new "root" for the post-compaction branch with no parent (empty ParentID). This breaks the parent chain so that old compacted messages are no longer traversed when building context. The kept messages are explicitly collected via FirstKeptEntryID in BuildContext.

func (*TreeManager) AppendExtensionData added in v0.3.0

func (tm *TreeManager) AppendExtensionData(extType, data string) (string, error)

AppendExtensionData adds an extension data entry to the tree and persists it. Extensions use this to store custom state that survives across session restarts.

func (*TreeManager) AppendIncompleteOutput added in v0.121.0

func (tm *TreeManager) AppendIncompleteOutput(ctx context.Context, attemptID, text string) (string, error)

AppendIncompleteOutput saves a transcript record without adding model history.

func (*TreeManager) AppendLLMMessage added in v0.30.0

func (tm *TreeManager) AppendLLMMessage(msg fantasy.Message) (string, error)

AppendLLMMessage converts an LLM message and appends it.

func (*TreeManager) AppendLabel

func (tm *TreeManager) AppendLabel(targetID, label string) (string, error)

AppendLabel sets a label on a target entry.

func (*TreeManager) AppendMessage

func (tm *TreeManager) AppendMessage(msg message.Message) (string, error)

AppendMessage adds a message entry to the tree and persists it.

func (*TreeManager) AppendModelChange

func (tm *TreeManager) AppendModelChange(provider, modelID string) (string, error)

AppendModelChange records a model/provider change.

func (*TreeManager) AppendSessionInfo

func (tm *TreeManager) AppendSessionInfo(name string) (string, error)

AppendSessionInfo sets a display name for the session.

func (*TreeManager) AppendStep added in v0.119.0

func (tm *TreeManager) AppendStep(ctx context.Context, msgs []fantasy.Message) ([]string, error)

AppendStep persists one agent step — the group of messages a single model request produced — with one buffered write, one flush, and one fsync.

A tool-calling step produces an assistant message carrying tool calls and a tool-role message carrying the matching results. Persisting them as one unit closes the crash window that would otherwise leave storage with a tool call and no result (providers reject that transcript, which makes the session unresumable). Kit calls this instead of looping over TreeManager.AppendMessage whenever the messages belong together; see also repairInterruptedToolCalls, which covers steps written by older versions that persisted per message.

Either every message is appended or none is: serialization happens for all messages before the first byte is written, and a failure anywhere in the write, flush, or sync is rolled back — the file is truncated to its pre-append offset and the buffered tail discarded, while the indices and the leaf pointer are only advanced after the whole step reached storage. If the rollback itself fails, the manager refuses all further appends: the file and the in-memory tree can no longer be kept in agreement, and silent divergence would fork the transcript.

ctx is accepted for signature compatibility with the durable-backend contract and is not used for cancellation: a finished step must survive the turn that produced it, even when the turn was cancelled (see the Cancellation section on kit's StepAppender).

func (*TreeManager) Branch

func (tm *TreeManager) Branch(entryID string) error

Branch moves the leaf pointer to the given entry ID, creating a branch point. Subsequent appends will extend from this new position.

func (*TreeManager) BuildContext

func (tm *TreeManager) BuildContext() (messages []fantasy.Message, provider string, modelID string)

BuildContext walks from the current leaf to the root and returns the conversation messages suitable for sending to the LLM. Compaction entries cause older messages to be replaced by the summary. Branch summaries are converted to user messages to provide context from abandoned branches. Also returns the latest model/provider settings encountered on the path.

Each returned message is a copy (see cloneLLMMessage), so callers, including SDK ContextPrepare hooks, may modify the result in place without corrupting the decoded-message cache behind it.

func (*TreeManager) Close

func (tm *TreeManager) Close() error

Close flushes any buffered writes, closes the underlying file handle, and releases the session file lock.

func (*TreeManager) DetectCycle added in v0.57.0

func (tm *TreeManager) DetectCycle(fromID string) (cycleDetected bool, cycleEntry string)

DetectCycle walks the parent chain from the given entry ID and returns true if a cycle is detected. This is used for diagnostics.

func (*TreeManager) EntryCount

func (tm *TreeManager) EntryCount() int

EntryCount returns the number of entries (excluding header).

func (*TreeManager) EntryID added in v0.30.0

func (tm *TreeManager) EntryID(entry any) string

EntryID extracts the ID from any entry type.

func (*TreeManager) Flush added in v0.59.0

func (tm *TreeManager) Flush() error

Flush writes any buffered data to the underlying file.

func (*TreeManager) ForkToNewSession added in v0.34.0

func (tm *TreeManager) ForkToNewSession(cwd string, targetID string) (*TreeManager, error)

ForkToNewSession creates a new session file containing the history up to and including the target entry ID. This matches Pi's /fork behavior: it creates a completely new session file with a parent_session reference, copying all entries from the root to the target point.

func (*TreeManager) GetBranch

func (tm *TreeManager) GetBranch(fromID string) []any

GetBranch returns the path of entries from the given entry to the root, ordered from root to the entry. If fromID is empty, uses the current leaf.

func (*TreeManager) GetChildren

func (tm *TreeManager) GetChildren(parentID string) []string

GetChildren returns direct child entry IDs for a given parent.

func (*TreeManager) GetContextEntryIDs added in v0.19.0

func (tm *TreeManager) GetContextEntryIDs() []string

GetContextEntryIDs returns the entry IDs corresponding to the fantasy messages returned by BuildContext, in the same order. Each entry ID maps to the session entry that produced the fantasy message at the same index. This is used by compaction to map a cut point index back to an entry ID.

A MessageEntry may produce more than one message; each of them gets the entry's ID. The returned slice has the same length as the messages slice from BuildContext. The compaction summary system message has no entry, so its position holds the empty string "".

func (*TreeManager) GetEntries

func (tm *TreeManager) GetEntries() []any

GetEntries returns all entries (excluding the session header).

func (*TreeManager) GetEntry

func (tm *TreeManager) GetEntry(id string) any

GetEntry returns the entry with the given ID, or nil if not found.

func (*TreeManager) GetExtensionData added in v0.3.0

func (tm *TreeManager) GetExtensionData(extType string) []*ExtensionDataEntry

GetExtensionData returns all extension data entries matching the given type, walking the current branch from root to leaf. If extType is empty, all extension data entries on the branch are returned.

func (*TreeManager) GetFilePath

func (tm *TreeManager) GetFilePath() string

GetFilePath returns the JSONL file path, or empty for in-memory sessions.

func (*TreeManager) GetHeader

func (tm *TreeManager) GetHeader() SessionHeader

GetHeader returns a copy of the session header.

func (*TreeManager) GetLLMMessages added in v0.30.0

func (tm *TreeManager) GetLLMMessages() []fantasy.Message

GetLLMMessages builds the context and returns just the messages. This satisfies the same conceptual role as the old Manager.GetMessages().

func (*TreeManager) GetLabel

func (tm *TreeManager) GetLabel(id string) string

GetLabel returns the label for an entry, or empty string if none.

func (*TreeManager) GetLastCompaction added in v0.19.0

func (tm *TreeManager) GetLastCompaction() *CompactionEntry

GetLastCompaction returns the most recent CompactionEntry on the current branch, or nil if none exists. Used to carry forward file tracking.

func (*TreeManager) GetLeafID

func (tm *TreeManager) GetLeafID() string

GetLeafID returns the current leaf position.

func (*TreeManager) GetSessionID

func (tm *TreeManager) GetSessionID() string

GetSessionID returns the session UUID.

func (*TreeManager) GetSessionName

func (tm *TreeManager) GetSessionName() string

GetSessionName returns the user-defined display name, or empty string.

func (*TreeManager) GetTree

func (tm *TreeManager) GetTree() []*TreeNode

GetTree builds the full tree structure from root entries.

func (*TreeManager) IsEmpty added in v0.25.0

func (tm *TreeManager) IsEmpty() bool

IsEmpty returns true if the session has no messages (only header).

func (*TreeManager) IsPersisted

func (tm *TreeManager) IsPersisted() bool

IsPersisted returns true if this session writes to disk.

func (*TreeManager) LogTreeDiagnostics added in v0.57.0

func (tm *TreeManager) LogTreeDiagnostics()

LogTreeDiagnostics logs information about the tree structure for debugging. Call this after OpenTreeSession or when anomalies are detected.

func (*TreeManager) MessageCount

func (tm *TreeManager) MessageCount() int

MessageCount returns the number of message entries.

func (*TreeManager) ResetLeaf

func (tm *TreeManager) ResetLeaf()

ResetLeaf moves the leaf pointer to before the first entry (empty conversation).

func (tm *TreeManager) SetParentLink(parentSessionPath, parentSessionID, subagentTask string) error

SetParentLink records a parent session reference (and, optionally, the originating subagent task) in the session header. It is used when a subagent-backed session is created from a session-backed parent so viewers can navigate the parent/child session tree.

For persisted sessions the header rewrite is atomic: the updated header plus all existing entries are written to a temp file which then replaces the original via rename, so a partial write can never corrupt the session. The session file lock is held for the whole rewrite except the rename itself (see below), and every error path either re-claims it or reports losing it, so the session never keeps appending unlocked. Sessions are typically freshly created when this is called, so the entry list is small (usually empty). For in-memory sessions the header is updated in memory only.

type TreeNode

type TreeNode struct {
	Entry    any         // the underlying entry (*MessageEntry, *ModelChangeEntry, etc.)
	ID       string      // entry ID
	ParentID string      // parent entry ID
	Children []*TreeNode // child nodes
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL