Documentation
¶
Overview ¶
Package session provides checkpoint session capture functionality for storing AI conversation segments linked to git commits and beads tasks.
Index ¶
- Constants
- func BuildStoragePath(projectID, featureBranch, identifier string) string
- func Compress(data []byte) ([]byte, error)
- func CompressionRatio(original, compressed int64) float64
- func Decompress(data []byte) ([]byte, error)
- func GetCurrentBranch(workdir string) (string, error)
- func GetCurrentCommitHash(workdir string) (string, error)
- func GetProjectID(workdir string) (string, error)
- func GetQueueDir() string
- func GetSessionStatePath() string
- func GetTranscriptSize(transcriptPath string) (int64, error)
- func IsGitCommit(toolInput string) bool
- func SaveSessionState(state *SessionState) error
- func UpdateSessionOffset(sessionID string, offset int64, commitHash string, transcriptPath string) error
- type CaptureResult
- type CreateSessionInput
- type HookInput
- type Message
- type MetadataClient
- func (m *MetadataClient) Create(accessToken string, input *CreateSessionInput) (*SessionMetadata, error)
- func (m *MetadataClient) GetByCommitHash(accessToken string, projectID string, commitHash string) (*SessionMetadata, error)
- func (m *MetadataClient) GetByID(accessToken string, sessionID string) (*SessionMetadata, error)
- func (m *MetadataClient) GetByTaskID(accessToken string, projectID string, taskID string) (*SessionMetadata, error)
- func (m *MetadataClient) ListByFeature(accessToken string, projectID string, featureBranch string) ([]SessionMetadata, error)
- func (m *MetadataClient) Query(accessToken string, opts *QueryOptions) ([]SessionMetadata, error)
- type QueryOptions
- type Queue
- func (q *Queue) Count() (int, error)
- func (q *Queue) Dequeue(sessionID string) error
- func (q *Queue) Enqueue(sessionID string, compressedData []byte, entry *QueueEntry) error
- func (q *Queue) GetQueuedSession(sessionID string) ([]byte, *QueueEntry, error)
- func (q *Queue) List() ([]string, error)
- func (q *Queue) ProcessQueue(accessToken string) (uploaded int, failed int, skipped int, errors []error)
- func (q *Queue) ShouldRetry(entry *QueueEntry) bool
- func (q *Queue) UpdateRetryCount(sessionID string) error
- type QueueEntry
- type SessionContent
- type SessionMetadata
- type SessionOffsetInfo
- type SessionState
- type SessionStatus
- type SignedURLResponse
- type StorageClient
- func (s *StorageClient) Download(accessToken string, storagePath string) ([]byte, error)
- func (s *StorageClient) GetSignedURL(accessToken string, storagePath string, expiresIn int) (*SignedURLResponse, error)
- func (s *StorageClient) Upload(accessToken string, storagePath string, data []byte) (*UploadResponse, error)
- type ToolInput
- type TranscriptLine
- type TranscriptMsg
- type UploadResponse
Constants ¶
const ( // MetadataTimeout is the timeout for metadata operations MetadataTimeout = 30 * time.Second // SessionsTable is the PostgREST table name SessionsTable = "sessions" )
const ( // MaxRetries is the maximum number of upload retries MaxRetries = 3 // RetryDelay is the initial delay between retries RetryDelay = 5 * time.Second )
const ( // StorageBucket is the Supabase Storage bucket for sessions StorageBucket = "sessions" // StorageTimeout is the timeout for storage operations (30 seconds) StorageTimeout = 30 * time.Second )
const MaxSessionSize = 10 * 1024 * 1024
MaxSessionSize is the maximum uncompressed session size (10 MB)
Variables ¶
This section is empty.
Functions ¶
func BuildStoragePath ¶
BuildStoragePath constructs the storage path for a session
func CompressionRatio ¶
CompressionRatio calculates the compression ratio (compressed/original)
func GetCurrentBranch ¶
GetCurrentBranch gets the current git branch name
func GetCurrentCommitHash ¶
GetCurrentCommitHash gets the current HEAD commit hash
func GetProjectID ¶
GetProjectID attempts to get the project ID from specledger.yaml
func GetQueueDir ¶
func GetQueueDir() string
GetQueueDir returns the path to the session queue directory
func GetSessionStatePath ¶
func GetSessionStatePath() string
GetSessionStatePath returns the path to the session state file
func GetTranscriptSize ¶
GetTranscriptSize returns the size of the transcript file
func IsGitCommit ¶
IsGitCommit checks if the tool input is a git commit command (but not amend)
func SaveSessionState ¶
func SaveSessionState(state *SessionState) error
SaveSessionState saves the session state to disk
Types ¶
type CaptureResult ¶
type CaptureResult struct {
Captured bool // whether a session was captured
SessionID string // the session ID if captured
StoragePath string // path in storage
MessageCount int // number of messages in the session
SizeBytes int64 // compressed size
RawSizeBytes int64 // uncompressed size
Queued bool // whether it was queued for later upload
Error error // any error that occurred
}
CaptureResult represents the outcome of a capture operation
func Capture ¶
func Capture(input *HookInput) *CaptureResult
Capture orchestrates the session capture flow
func CaptureFromStdin ¶
func CaptureFromStdin() *CaptureResult
CaptureFromStdin reads hook input from stdin and captures the session
type CreateSessionInput ¶
type CreateSessionInput struct {
ProjectID string `json:"project_id"`
FeatureBranch string `json:"feature_branch"`
CommitHash *string `json:"commit_hash,omitempty"`
TaskID *string `json:"task_id,omitempty"`
AuthorID string `json:"author_id"`
StoragePath string `json:"storage_path"`
Status SessionStatus `json:"status"`
SizeBytes int64 `json:"size_bytes"`
RawSizeBytes int64 `json:"raw_size_bytes"`
MessageCount int `json:"message_count"`
}
CreateSessionInput represents the input for creating a session
type HookInput ¶
type HookInput struct {
SessionID string `json:"session_id"`
TranscriptPath string `json:"transcript_path"`
Cwd string `json:"cwd"`
HookEventName string `json:"hook_event_name"`
ToolName string `json:"tool_name"`
ToolInput ToolInput `json:"tool_input"` // the command that was run
ToolOutput string `json:"tool_output"` // output from the tool
ToolDurationMs int64 `json:"tool_duration_ms"` // how long the tool took
ToolSuccess bool `json:"tool_success"` // whether the tool succeeded
}
HookInput represents the JSON input from Claude Code hooks
func ParseHookInput ¶
ParseHookInput parses the hook input from stdin
type Message ¶
type Message struct {
Role string `json:"role"` // "user" or "assistant"
Content string `json:"content"` // message content
Timestamp time.Time `json:"timestamp"` // when the message was sent
}
Message represents a single message in the conversation
type MetadataClient ¶
type MetadataClient struct {
// contains filtered or unexported fields
}
MetadataClient handles Supabase PostgREST operations for session metadata
func NewMetadataClient ¶
func NewMetadataClient() *MetadataClient
NewMetadataClient creates a new metadata client
func (*MetadataClient) Create ¶
func (m *MetadataClient) Create(accessToken string, input *CreateSessionInput) (*SessionMetadata, error)
Create creates a new session metadata record
func (*MetadataClient) GetByCommitHash ¶
func (m *MetadataClient) GetByCommitHash(accessToken string, projectID string, commitHash string) (*SessionMetadata, error)
GetByCommitHash retrieves a session by project and commit hash
func (*MetadataClient) GetByID ¶
func (m *MetadataClient) GetByID(accessToken string, sessionID string) (*SessionMetadata, error)
GetByID retrieves a session by its ID
func (*MetadataClient) GetByTaskID ¶
func (m *MetadataClient) GetByTaskID(accessToken string, projectID string, taskID string) (*SessionMetadata, error)
GetByTaskID retrieves a session by project and task ID
func (*MetadataClient) ListByFeature ¶
func (m *MetadataClient) ListByFeature(accessToken string, projectID string, featureBranch string) ([]SessionMetadata, error)
ListByFeature retrieves all sessions for a feature branch
func (*MetadataClient) Query ¶
func (m *MetadataClient) Query(accessToken string, opts *QueryOptions) ([]SessionMetadata, error)
Query queries sessions based on options
type QueryOptions ¶
type QueryOptions struct {
ProjectID string
FeatureBranch string
CommitHash string
TaskID string
AuthorID string
StartDate *time.Time
EndDate *time.Time
Limit int
Offset int
OrderBy string
OrderDesc bool
}
QueryOptions represents options for querying sessions
type Queue ¶
type Queue struct {
// contains filtered or unexported fields
}
Queue manages the local session upload queue
func (*Queue) Enqueue ¶
func (q *Queue) Enqueue(sessionID string, compressedData []byte, entry *QueueEntry) error
Enqueue adds a session to the upload queue
func (*Queue) GetQueuedSession ¶
func (q *Queue) GetQueuedSession(sessionID string) ([]byte, *QueueEntry, error)
GetQueuedSession retrieves a queued session's data and metadata
func (*Queue) ProcessQueue ¶
func (q *Queue) ProcessQueue(accessToken string) (uploaded int, failed int, skipped int, errors []error)
ProcessQueue attempts to upload all queued sessions
func (*Queue) ShouldRetry ¶
func (q *Queue) ShouldRetry(entry *QueueEntry) bool
ShouldRetry checks if a session should be retried
func (*Queue) UpdateRetryCount ¶
UpdateRetryCount updates the retry count for a queued session
type QueueEntry ¶
type QueueEntry struct {
SessionID string `json:"session_id"`
ProjectID string `json:"project_id"`
FeatureBranch string `json:"feature_branch"`
CommitHash *string `json:"commit_hash,omitempty"`
TaskID *string `json:"task_id,omitempty"`
AuthorID string `json:"author_id"`
Status SessionStatus `json:"status"`
CreatedAt time.Time `json:"created_at"`
RetryCount int `json:"retry_count"`
LastRetry *time.Time `json:"last_retry,omitempty"`
}
QueueEntry represents a session queued for upload
type SessionContent ¶
type SessionContent struct {
Version string `json:"version"` // schema version (e.g., "1.0")
SessionID string `json:"session_id"` // unique identifier
FeatureBranch string `json:"feature_branch"` // e.g., "010-checkpoint-session-capture"
CommitHash string `json:"commit_hash"` // git commit hash (nullable for task sessions)
TaskID string `json:"task_id"` // beads task ID (nullable for commit sessions)
Author string `json:"author"` // user email
CapturedAt time.Time `json:"captured_at"` // when captured
Messages []Message `json:"messages"` // conversation messages
}
SessionContent represents the full session data stored in Supabase Storage
type SessionMetadata ¶
type SessionMetadata struct {
ID string `json:"id"`
ProjectID string `json:"project_id"`
FeatureBranch string `json:"feature_branch"`
CommitHash *string `json:"commit_hash,omitempty"`
TaskID *string `json:"task_id,omitempty"`
AuthorID string `json:"author_id"`
StoragePath string `json:"storage_path"`
Status SessionStatus `json:"status"`
SizeBytes int64 `json:"size_bytes"` // compressed size
RawSizeBytes int64 `json:"raw_size_bytes"` // uncompressed size
MessageCount int `json:"message_count"`
CreatedAt time.Time `json:"created_at"`
}
SessionMetadata represents the queryable metadata stored in the database
type SessionOffsetInfo ¶
type SessionOffsetInfo struct {
LastOffset int64 `json:"last_offset"` // byte offset in transcript file
LastCommit string `json:"last_commit"` // last commit hash captured
TranscriptPath string `json:"transcript_path"` // path to the transcript file
}
SessionOffsetInfo tracks the last captured position in the transcript
func GetSessionOffset ¶
func GetSessionOffset(sessionID string) (*SessionOffsetInfo, error)
GetSessionOffset retrieves the last offset for a session
type SessionState ¶
type SessionState struct {
Sessions map[string]*SessionOffsetInfo `json:"sessions"`
}
SessionState represents the local tracking state for delta computation
func LoadSessionState ¶
func LoadSessionState() (*SessionState, error)
LoadSessionState loads the session state from disk
type SessionStatus ¶
type SessionStatus string
SessionStatus represents the completion status of a session
const ( StatusComplete SessionStatus = "complete" StatusRejected SessionStatus = "rejected" StatusAbandoned SessionStatus = "abandoned" )
type SignedURLResponse ¶
type SignedURLResponse struct {
SignedURL string `json:"signedURL"`
}
SignedURLResponse represents the response from signed URL generation
type StorageClient ¶
type StorageClient struct {
// contains filtered or unexported fields
}
StorageClient handles Supabase Storage operations
func NewStorageClient ¶
func NewStorageClient() *StorageClient
NewStorageClient creates a new storage client
func (*StorageClient) Download ¶
func (s *StorageClient) Download(accessToken string, storagePath string) ([]byte, error)
Download downloads session content from Supabase Storage
func (*StorageClient) GetSignedURL ¶
func (s *StorageClient) GetSignedURL(accessToken string, storagePath string, expiresIn int) (*SignedURLResponse, error)
GetSignedURL generates a time-limited signed URL for session content
func (*StorageClient) Upload ¶
func (s *StorageClient) Upload(accessToken string, storagePath string, data []byte) (*UploadResponse, error)
Upload uploads compressed session content to Supabase Storage
type ToolInput ¶ added in v1.0.17
type ToolInput struct {
Raw json.RawMessage
}
ToolInput represents the tool_input field from Claude Code hooks. For Bash tools, this is {"command": "..."}. We use json.RawMessage to handle both object and string formats.
func (*ToolInput) Command ¶ added in v1.0.17
Command extracts the command string from the tool input. Handles both object format {"command": "..."} and plain string format.
func (*ToolInput) UnmarshalJSON ¶ added in v1.0.17
type TranscriptLine ¶
type TranscriptLine struct {
Type string `json:"type"` // "user", "assistant", "tool_use", etc.
Message *TranscriptMsg `json:"message,omitempty"` // nested message object
Content string `json:"content,omitempty"` // direct content (fallback)
Timestamp time.Time `json:"timestamp"` // when recorded
UUID string `json:"uuid,omitempty"` // message UUID
Role string `json:"role,omitempty"` // alternative to type
}
TranscriptLine represents a single line from the Claude Code transcript JSONL
type TranscriptMsg ¶
type TranscriptMsg struct {
Role string `json:"role"` // "user" or "assistant"
Content interface{} `json:"content,omitempty"` // string or array of content blocks
}
TranscriptMsg represents the nested message in Claude Code transcripts
type UploadResponse ¶
UploadResponse represents the response from an upload operation