statedb

package
v1.7.21 Latest Latest
Warning

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

 Go to latest Published: Apr 18, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Index

Constants

View Source 
const SchemaVersion = 5

SchemaVersion tracks the current database schema version. Bump this when adding migrations.

Variables

This section is empty.

Functions

func MarshalToolData 

func MarshalToolData(
	claudeSessionID string, claudeDetectedAt time.Time,
	geminiSessionID string, geminiDetectedAt time.Time,
	geminiYoloMode *bool, geminiModel string,
	openCodeSessionID string, openCodeDetectedAt time.Time,
	codexSessionID string, codexDetectedAt time.Time,
	latestPrompt string, notes string, loadedMCPNames []string,
	toolOptionsJSON json.RawMessage,
	sandboxJSON json.RawMessage, sandboxContainer string,
	sshHost string, sshRemotePath string,
	multiRepoEnabled bool, additionalPaths []string,
	multiRepoTempDir string, multiRepoWorktrees []MultiRepoWorktreeData,
	channels []string,
	extraArgs []string,
) json.RawMessage

func MigrateFromJSON 

func MigrateFromJSON(jsonPath string, db *StateDB) (int, int, error)

MigrateFromJSON reads a sessions.json file and inserts all data into the StateDB. Returns the number of instances and groups migrated.

func SetGlobal 

func SetGlobal(db *StateDB)

SetGlobal sets the global StateDB instance.

Types

type GroupRow 

type GroupRow struct {
	Path        string
	Name        string
	Expanded    bool
	Order       int
	DefaultPath string
}

GroupRow represents a group row in the database.

type InstanceRow 

type InstanceRow struct {
	ID              string
	Title           string
	ProjectPath     string
	GroupPath       string
	Order           int
	Command         string
	Wrapper         string
	Tool            string
	Status          string
	TmuxSession     string
	CreatedAt       time.Time
	LastAccessed    time.Time
	ParentSessionID string
	IsConductor     bool
	WorktreePath    string
	WorktreeRepo    string
	WorktreeBranch  string
	ToolData        json.RawMessage // JSON blob for tool-specific data
}

InstanceRow represents a session row in the database.

type MultiRepoWorktreeData added in v0.26.2 

type MultiRepoWorktreeData struct {
	OriginalPath string
	WorktreePath string
	RepoRoot     string
	Branch       string
}

MarshalToolData creates a tool_data JSON blob from individual fields. This is the forward path: Instance fields -> JSON blob for SQLite storage. MultiRepoWorktreeData holds multi-repo worktree info for serialization.

func UnmarshalToolData 

func UnmarshalToolData(data json.RawMessage) (
	claudeSessionID string, claudeDetectedAt time.Time,
	geminiSessionID string, geminiDetectedAt time.Time,
	geminiYoloMode *bool, geminiModel string,
	openCodeSessionID string, openCodeDetectedAt time.Time,
	codexSessionID string, codexDetectedAt time.Time,
	latestPrompt string, notes string, loadedMCPNames []string,
	toolOptionsJSON json.RawMessage,
	sandboxJSON json.RawMessage, sandboxContainer string,
	sshHost string, sshRemotePath string,
	multiRepoEnabled bool, additionalPaths []string,
	multiRepoTempDir string, multiRepoWorktrees []MultiRepoWorktreeData,
	channels []string,
	extraArgs []string,
)

UnmarshalToolData extracts individual fields from the tool_data JSON blob. This is the reverse path: JSON blob from SQLite -> individual Instance fields.

type RecentSessionRow added in v0.20.0 

type RecentSessionRow struct {
	ID             string // SHA-256 dedup key (title+path+tool+group)
	Title          string
	ProjectPath    string
	GroupPath      string
	Command        string
	Wrapper        string
	Tool           string
	ToolOptions    json.RawMessage // serialized ToolOptionsWrapper
	SandboxEnabled bool
	GeminiYoloMode *bool
	DeletedAt      time.Time
}

RecentSessionRow captures the config of a deleted session for quick re-creation.

type StateDB 

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

StateDB wraps a SQLite database for session/group persistence. Thread-safe for concurrent use from multiple goroutines within one process. Multiple OS processes can safely read/write via WAL mode + busy timeout.

func GetGlobal 

func GetGlobal() *StateDB

GetGlobal returns the global StateDB instance (may be nil).

func Open 

func Open(dbPath string) (*StateDB, error)

Open creates or opens a SQLite database at dbPath with WAL mode and busy timeout.

func (*StateDB) AliveInstanceCount 

func (s *StateDB) AliveInstanceCount() (int, error)

AliveInstanceCount returns how many TUI instances have fresh heartbeats.

func (*StateDB) CleanDeadInstances 

func (s *StateDB) CleanDeadInstances(timeout time.Duration) error

CleanDeadInstances removes heartbeat entries that haven't been updated within timeout.

func (*StateDB) Close 

func (s *StateDB) Close() error

Close checkpoints WAL and closes the database.

func (*StateDB) DB 

func (s *StateDB) DB() *sql.DB

DB returns the underlying sql.DB for advanced use cases (e.g., testing).

func (*StateDB) DeleteGroup 

func (s *StateDB) DeleteGroup(path string) error

DeleteGroup removes a group by path.

func (*StateDB) DeleteInstance 

func (s *StateDB) DeleteInstance(id string) error

DeleteInstance removes an instance by ID.

func (*StateDB) ElectPrimary added in v0.11.1 

func (s *StateDB) ElectPrimary(timeout time.Duration) (bool, error)

ElectPrimary attempts to make this instance the primary. Returns true if this instance is now (or already was) the primary. Uses a transaction to atomically clear stale primaries and claim if available.

func (*StateDB) GetMeta 

func (s *StateDB) GetMeta(key string) (string, error)

GetMeta gets a value from the metadata table. Returns "" if not found.

func (*StateDB) Heartbeat 

func (s *StateDB) Heartbeat() error

Heartbeat updates the heartbeat timestamp for this process.

func (*StateDB) IsEmpty 

func (s *StateDB) IsEmpty() (bool, error)

IsEmpty returns true if the instances table has no rows.

func (*StateDB) LastModified 

func (s *StateDB) LastModified() (int64, error)

LastModified returns the last_modified timestamp from metadata.

func (*StateDB) LoadGroups 

func (s *StateDB) LoadGroups() ([]*GroupRow, error)

LoadGroups returns all groups ordered by sort_order.

func (*StateDB) LoadInstances 

func (s *StateDB) LoadInstances() ([]*InstanceRow, error)

LoadInstances returns all instances ordered by sort_order.

func (*StateDB) LoadRecentSessions added in v0.20.0 

func (s *StateDB) LoadRecentSessions() ([]*RecentSessionRow, error)

LoadRecentSessions returns all recent sessions ordered by most recently deleted.

func (*StateDB) LoadWatcherByName added in v1.5.1 

func (s *StateDB) LoadWatcherByName(name string) (*WatcherRow, error)

LoadWatcherByName returns the watcher with the given name, or nil if not found. A missing watcher is not an error; (nil, nil) is returned.

func (*StateDB) LoadWatcherEvents added in v1.5.1 

func (s *StateDB) LoadWatcherEvents(watcherID string, limit int) ([]WatcherEventRow, error)

LoadWatcherEvents returns up to limit events for the given watcher, ordered most recent first.

func (*StateDB) LoadWatchers added in v1.5.1 

func (s *StateDB) LoadWatchers() ([]*WatcherRow, error)

LoadWatchers returns all watchers ordered by name.

func (*StateDB) LookupWatcherEventSessionByDedupKey added in v1.5.1 

func (s *StateDB) LookupWatcherEventSessionByDedupKey(watcherID, dedupKey string) (string, error)

LookupWatcherEventSessionByDedupKey queries the session_id for a specific event. Returns ("", nil) if no matching event exists or session_id is empty.

func (*StateDB) LookupWatcherIDByDedupKey added in v1.5.1 

func (s *StateDB) LookupWatcherIDByDedupKey(dedupKey string) (string, error)

LookupWatcherIDByDedupKey returns the watcher_id for the first watcher_events row with the given dedup_key. Returns an error if no row is found. Used by the triageReaper to correlate a result.json back to its originating event (D-08).

func (*StateDB) Migrate 

func (s *StateDB) Migrate() error

Migrate creates tables if they don't exist and runs any pending migrations.

func (*StateDB) ReadAllStatuses 

func (s *StateDB) ReadAllStatuses() (map[string]StatusRow, error)

ReadAllStatuses returns status + acknowledged flag for every instance.

func (*StateDB) RegisterInstance 

func (s *StateDB) RegisterInstance(isPrimary bool) error

RegisterInstance records this process as an active TUI instance.

func (*StateDB) ResignPrimary added in v0.11.1 

func (s *StateDB) ResignPrimary() error

ResignPrimary clears the is_primary flag for this process.

func (*StateDB) SaveGroups 

func (s *StateDB) SaveGroups(groups []*GroupRow) error

SaveGroups replaces all groups in a single transaction.

func (*StateDB) SaveInstance 

func (s *StateDB) SaveInstance(inst *InstanceRow) error

SaveInstance inserts or replaces a single instance.

func (*StateDB) SaveInstances 

func (s *StateDB) SaveInstances(insts []*InstanceRow) error

SaveInstances inserts or replaces multiple instances in a single transaction. It also removes any rows from the database that are not in the provided list, ensuring deleted sessions don't reappear on reload.

func (*StateDB) SaveRecentSession added in v0.20.0 

func (s *StateDB) SaveRecentSession(row *RecentSessionRow) error

SaveRecentSession inserts or replaces a recent session entry, then prunes to 20.

func (*StateDB) SaveWatcher added in v1.5.1 

func (s *StateDB) SaveWatcher(w *WatcherRow) error

SaveWatcher inserts or replaces a watcher row.

func (*StateDB) SaveWatcherEvent added in v1.5.1 

func (s *StateDB) SaveWatcherEvent(watcherID, dedupKey, sender, subject, routedTo, sessionID string, maxEvents int) (bool, error)

SaveWatcherEvent inserts an event with dedup via INSERT OR IGNORE. Returns true if the row was inserted (new event), false if it was a duplicate. Prunes to maxEvents after successful insert.

func (*StateDB) SetAcknowledged 

func (s *StateDB) SetAcknowledged(id string, ack bool) error

SetAcknowledged sets or clears the acknowledged flag for an instance.

func (*StateDB) SetMeta 

func (s *StateDB) SetMeta(key, value string) error

SetMeta sets a key-value pair in the metadata table.

func (*StateDB) Touch 

func (s *StateDB) Touch() error

Touch updates a metadata timestamp that other instances can poll to detect changes.

func (*StateDB) UnregisterInstance 

func (s *StateDB) UnregisterInstance() error

UnregisterInstance removes this process from the heartbeat table.

func (*StateDB) UpdateInstanceField 

func (s *StateDB) UpdateInstanceField(id, field string, value any) error

UpdateInstanceField updates a single column for a given instance. field must be a valid column name (caller is responsible for safety).

func (*StateDB) UpdateWatcherEventRoutedTo added in v1.5.1 

func (s *StateDB) UpdateWatcherEventRoutedTo(watcherID, dedupKey, routedTo, triageSessionID string) error

UpdateWatcherEventRoutedTo updates the routed_to and triage_session_id columns for the row matching (watcher_id, dedup_key). Returns a wrapped error if no row matches (0 rows affected), allowing the caller to distinguish "update OK" from "event not found".

func (*StateDB) UpdateWatcherEventSessionID added in v1.5.1 

func (s *StateDB) UpdateWatcherEventSessionID(watcherID, dedupKey, sessionID string) error

UpdateWatcherEventSessionID sets the session_id on an existing watcher event. Returns an error if no matching row exists (0 rows affected).

func (*StateDB) UpdateWatcherStatus added in v1.5.1 

func (s *StateDB) UpdateWatcherStatus(watcherID string, status string) error

UpdateWatcherStatus sets the status field on a watcher row. Returns an error if no watcher with the given ID exists.

func (*StateDB) WriteStatus 

func (s *StateDB) WriteStatus(id, status, tool string) error

WriteStatus updates the status and tool for an instance.

type StatusRow 

type StatusRow struct {
	Status       string
	Tool         string
	Acknowledged bool
}

StatusRow holds status + acknowledgment for a session.

type WatcherEventRow added in v1.5.1 

type WatcherEventRow struct {
	ID        int64
	WatcherID string
	DedupKey  string
	Sender    string
	Subject   string
	RoutedTo  string
	SessionID string
	CreatedAt time.Time
}

WatcherEventRow represents a single event row from the watcher_events table.

type WatcherRow added in v1.5.1 

type WatcherRow struct {
	ID         string
	Name       string
	Type       string
	ConfigPath string
	Status     string
	Conductor  string
	CreatedAt  time.Time
	UpdatedAt  time.Time
}

WatcherRow represents a watcher row in the database.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.