Documentation
¶
Index ¶
- type PromptAttribution
- type State
- type StateStore
- func (s *StateStore) Clear(ctx context.Context, sessionID string) error
- func (s *StateStore) List(ctx context.Context) ([]*State, error)
- func (s *StateStore) Load(ctx context.Context, sessionID string) (*State, error)
- func (s *StateStore) RemoveAll() error
- func (s *StateStore) Save(ctx context.Context, state *State) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type PromptAttribution ¶
type PromptAttribution struct {
// CheckpointNumber is which checkpoint this was recorded before (1-indexed)
CheckpointNumber int `json:"checkpoint_number"`
// UserLinesAdded is lines added by user since the last checkpoint
UserLinesAdded int `json:"user_lines_added"`
// UserLinesRemoved is lines removed by user since the last checkpoint
UserLinesRemoved int `json:"user_lines_removed"`
// AgentLinesAdded is total agent lines added so far (base → last checkpoint).
// Always 0 for checkpoint 1 since there's no previous checkpoint to measure against.
AgentLinesAdded int `json:"agent_lines_added"`
// AgentLinesRemoved is total agent lines removed so far (base → last checkpoint).
// Always 0 for checkpoint 1 since there's no previous checkpoint to measure against.
AgentLinesRemoved int `json:"agent_lines_removed"`
// UserAddedPerFile tracks per-file user additions for accurate modification tracking.
// This enables distinguishing user self-modifications from agent modifications.
// See docs/architecture/attribution.md for details.
UserAddedPerFile map[string]int `json:"user_added_per_file,omitempty"`
}
PromptAttribution captures line-level attribution data at the start of each prompt. By recording what changed since the last checkpoint BEFORE the agent works, we can accurately separate user edits from agent contributions.
type State ¶
type State struct {
// SessionID is the unique session identifier
SessionID string `json:"session_id"`
// BaseCommit is the HEAD commit when the session started
BaseCommit string `json:"base_commit"`
// WorktreePath is the absolute path to the worktree root
WorktreePath string `json:"worktree_path,omitempty"`
// WorktreeID is the internal git worktree identifier (empty for main worktree)
// Derived from .git/worktrees/<name>/, stable across git worktree move
WorktreeID string `json:"worktree_id,omitempty"`
// StartedAt is when the session was started
StartedAt time.Time `json:"started_at"`
// EndedAt is when the session was explicitly closed by the user.
// nil means the session is still active or was not cleanly closed.
EndedAt *time.Time `json:"ended_at,omitempty"`
// CheckpointCount is the number of checkpoints created in this session
CheckpointCount int `json:"checkpoint_count"`
// CondensedTranscriptLines tracks lines already included in previous condensation
CondensedTranscriptLines int `json:"condensed_transcript_lines,omitempty"`
// UntrackedFilesAtStart tracks files that existed at session start (to preserve during rewind)
UntrackedFilesAtStart []string `json:"untracked_files_at_start,omitempty"`
// FilesTouched tracks files modified/created/deleted during this session
FilesTouched []string `json:"files_touched,omitempty"`
// LastCheckpointID is the checkpoint ID from last condensation, reused for subsequent commits without new content
LastCheckpointID id.CheckpointID `json:"last_checkpoint_id,omitempty"`
// AgentType identifies the agent that created this session (e.g., "Claude Code", "Gemini CLI", "Cursor")
AgentType agent.AgentType `json:"agent_type,omitempty"`
// Token usage tracking (accumulated across all checkpoints in this session)
TokenUsage *agent.TokenUsage `json:"token_usage,omitempty"`
// Transcript position when session started (for multi-session checkpoints)
TranscriptLinesAtStart int `json:"transcript_lines_at_start,omitempty"`
TranscriptIdentifierAtStart string `json:"transcript_identifier_at_start,omitempty"`
// TranscriptPath is the path to the live transcript file (for mid-session commit detection)
TranscriptPath string `json:"transcript_path,omitempty"`
// PromptAttributions tracks user and agent line changes at each prompt start.
// This enables accurate attribution by capturing user edits between checkpoints.
PromptAttributions []PromptAttribution `json:"prompt_attributions,omitempty"`
// PendingPromptAttribution holds attribution calculated at prompt start (before agent runs).
// This is moved to PromptAttributions when SaveChanges is called.
PendingPromptAttribution *PromptAttribution `json:"pending_prompt_attribution,omitempty"`
}
State represents the state of an active session. This is stored in .git/entire-sessions/<session-id>.json
type StateStore ¶
type StateStore struct {
// contains filtered or unexported fields
}
StateStore provides low-level operations for managing session state files.
StateStore is a primitive for session state persistence. It is NOT the same as the Sessions interface - it only handles state files in .git/entire-sessions/, not the full session data which includes checkpoint content.
Use StateStore directly in strategies for performance-critical state operations. Use the Sessions interface (when implemented) for high-level session management.
func NewStateStore ¶
func NewStateStore() (*StateStore, error)
NewStateStore creates a new state store. Uses the git common dir to store session state (shared across worktrees).
func NewStateStoreWithDir ¶
func NewStateStoreWithDir(stateDir string) *StateStore
NewStateStoreWithDir creates a new state store with a custom directory. This is useful for testing.
func (*StateStore) Clear ¶
func (s *StateStore) Clear(ctx context.Context, sessionID string) error
Clear removes the session state file for the given session ID.
func (*StateStore) List ¶
func (s *StateStore) List(ctx context.Context) ([]*State, error)
List returns all session states.
func (*StateStore) Load ¶
Load loads the session state for the given session ID. Returns (nil, nil) when session file doesn't exist (not an error condition).
func (*StateStore) RemoveAll ¶
func (s *StateStore) RemoveAll() error
RemoveAll removes the entire session state directory. This is used during uninstall to completely remove all session state.