Documentation
¶
Overview ¶
Package store wraps the SQLite database that holds mosaic state. It owns the connection lifecycle, schema migrations, and the repositories that mosaic subsystems use to read and write rows.
The package uses modernc.org/sqlite (a pure-Go SQLite driver) so that mosaic can be cross-compiled without CGO.
Index ¶
- Constants
- Variables
- func NewSessionID() (string, error)
- type Artifact
- type ArtifactsRepo
- func (r *ArtifactsRepo) Delete(ctx context.Context, id string) error
- func (r *ArtifactsRepo) GetByHash(ctx context.Context, sessionID, hash string) (Artifact, error)
- func (r *ArtifactsRepo) ListAll(ctx context.Context) (map[string][]Artifact, error)
- func (r *ArtifactsRepo) ListBySession(ctx context.Context, sessionID string) ([]Artifact, error)
- func (r *ArtifactsRepo) Upsert(ctx context.Context, in NewArtifact) (Artifact, bool, error)
- type AttentionState
- type Conductor
- type ConductorStatus
- type ConductorTask
- type ConductorsRepo
- func (r *ConductorsRepo) AssignTask(ctx context.Context, id, sessionID string) error
- func (r *ConductorsRepo) GetByID(ctx context.Context, id string) (Conductor, error)
- func (r *ConductorsRepo) Inbox(ctx context.Context, sessionID string) ([]Message, error)
- func (r *ConductorsRepo) Insert(ctx context.Context, in NewConductor) (Conductor, error)
- func (r *ConductorsRepo) InsertTask(ctx context.Context, in NewConductorTask) (ConductorTask, error)
- func (r *ConductorsRepo) List(ctx context.Context) ([]Conductor, error)
- func (r *ConductorsRepo) ListTasks(ctx context.Context, conductorID string) ([]ConductorTask, error)
- func (r *ConductorsRepo) MarkDelivered(ctx context.Context, sessionID string) error
- func (r *ConductorsRepo) PostMessage(ctx context.Context, in NewMessage) (Message, error)
- func (r *ConductorsRepo) SetStatus(ctx context.Context, id string, status ConductorStatus) error
- func (r *ConductorsRepo) SetTaskStatus(ctx context.Context, id string, status TaskStatus) error
- type Message
- type NewArtifact
- type NewConductor
- type NewConductorTask
- type NewMessage
- type NewNotification
- type NewSession
- type NewSubagent
- type Notification
- type NotificationSource
- type NotificationsRepo
- func (r *NotificationsRepo) Dismiss(ctx context.Context, sessionID string) error
- func (r *NotificationsRepo) GetByID(ctx context.Context, id int64) (Notification, error)
- func (r *NotificationsRepo) Insert(ctx context.Context, in NewNotification) (Notification, error)
- func (r *NotificationsRepo) ListUnseen(ctx context.Context, sessionID string) ([]Notification, error)
- type Session
- type SessionMCP
- type SessionMCPsRepo
- func (r *SessionMCPsRepo) Attach(ctx context.Context, sessionID, mcpName string) error
- func (r *SessionMCPsRepo) AttachedNames(ctx context.Context, sessionID string) (map[string]bool, error)
- func (r *SessionMCPsRepo) Detach(ctx context.Context, sessionID, mcpName string) error
- func (r *SessionMCPsRepo) ForSession(ctx context.Context, sessionID string) ([]SessionMCP, error)
- func (r *SessionMCPsRepo) IsAttached(ctx context.Context, sessionID, mcpName string) (bool, error)
- type SessionSkill
- type SessionSkillsRepo
- func (r *SessionSkillsRepo) Attach(ctx context.Context, sessionID, skillName string) error
- func (r *SessionSkillsRepo) AttachedNames(ctx context.Context, sessionID string) (map[string]bool, error)
- func (r *SessionSkillsRepo) Detach(ctx context.Context, sessionID, skillName string) error
- func (r *SessionSkillsRepo) ForSession(ctx context.Context, sessionID string) ([]SessionSkill, error)
- func (r *SessionSkillsRepo) IsAttached(ctx context.Context, sessionID, skillName string) (bool, error)
- type SessionStatus
- type SessionTool
- type SessionsRepo
- func (r *SessionsRepo) BindAgentSession(ctx context.Context, id string, runtime SessionTool, ...) error
- func (r *SessionsRepo) BindClaudeSession(ctx context.Context, id, claudeSessionID string) error
- func (r *SessionsRepo) Delete(ctx context.Context, id string) error
- func (r *SessionsRepo) GetByID(ctx context.Context, id string) (Session, error)
- func (r *SessionsRepo) GetByName(ctx context.Context, name string) (Session, error)
- func (r *SessionsRepo) Insert(ctx context.Context, in NewSession) (Session, error)
- func (r *SessionsRepo) List(ctx context.Context) ([]Session, error)
- func (r *SessionsRepo) SetAttention(ctx context.Context, id string, state AttentionState, ...) error
- func (r *SessionsRepo) UpdateStatus(ctx context.Context, id string, status SessionStatus) error
- type Store
- func (s *Store) AppliedVersions(ctx context.Context) (map[int]bool, error)
- func (s *Store) Artifacts() *ArtifactsRepo
- func (s *Store) Close() error
- func (s *Store) Conductors() *ConductorsRepo
- func (s *Store) DB() *sqlx.DB
- func (s *Store) Migrate(ctx context.Context) error
- func (s *Store) Notifications() *NotificationsRepo
- func (s *Store) SessionMCPs() *SessionMCPsRepo
- func (s *Store) SessionSkills() *SessionSkillsRepo
- func (s *Store) Sessions() *SessionsRepo
- func (s *Store) Subagents() *SubagentsRepo
- func (s *Store) WALCheckpoint() error
- type Subagent
- type SubagentMeta
- type SubagentStatus
- type SubagentsRepo
- func (r *SubagentsRepo) GetByAgentID(ctx context.Context, parentSessionID, agentID string) (Subagent, error)
- func (r *SubagentsRepo) ListByParent(ctx context.Context, parentSessionID string) ([]Subagent, error)
- func (r *SubagentsRepo) ListRunning(ctx context.Context) ([]Subagent, error)
- func (r *SubagentsRepo) MarkCompleted(ctx context.Context, id string) error
- func (r *SubagentsRepo) MarkErrored(ctx context.Context, id string) error
- func (r *SubagentsRepo) PromoteSpawning(ctx context.Context, id string) error
- func (r *SubagentsRepo) SetEventOffset(ctx context.Context, id string, offset int64) error
- func (r *SubagentsRepo) SetMetadata(ctx context.Context, id string, meta SubagentMeta) error
- func (r *SubagentsRepo) UpdateRunningTool(ctx context.Context, id, toolName string, startedAt time.Time) error
- func (r *SubagentsRepo) Upsert(ctx context.Context, in NewSubagent) (Subagent, error)
- type TaskStatus
Constants ¶
const DefaultSubagentType = "general-purpose"
DefaultSubagentType is the placeholder subagent_type used when Claude Code does not specify one explicitly (i.e. the user wrote Agent without a subagent_type parameter). Exported so the TUI, Discord, and reconciler can filter it out of display labels.
Variables ¶
var ErrArtifactNotFound = errors.New("artifact not found")
ErrArtifactNotFound is returned when a lookup misses.
var ErrConductorNotFound = errors.New("conductor not found")
ErrConductorNotFound is returned when a lookup misses.
var ErrSessionNotFound = errors.New("session not found")
ErrSessionNotFound is returned by SessionsRepo.GetByID and friends when no row matches.
var ErrSubagentNotFound = errors.New("subagent not found")
ErrSubagentNotFound is returned when a lookup misses.
Functions ¶
func NewSessionID ¶ added in v0.6.0
NewSessionID mints a fresh session ULID without touching the database. It is the public entry point for callers that need the ID before calling SessionsRepo.Insert (typically so they can derive related identifiers — the sandbox container name, for example — and pass them in via NewSession instead of letting Insert synthesise them).
Types ¶
type Artifact ¶ added in v0.11.0
type Artifact struct {
ID string `db:"id"`
SessionID string `db:"session_id"`
Kind string `db:"kind"`
Source string `db:"source"`
AgentID string `db:"agent_id"`
Title string `db:"title"`
Content sql.NullString `db:"content"`
Path string `db:"path"`
ContentHash string `db:"content_hash"`
CreatedAt time.Time `db:"created_at"`
}
Artifact is the row type for the artifacts table: a piece of rich content (Mermaid diagram, image, HTML page or URL) that belongs to a session and that the viewer can open.
type ArtifactsRepo ¶ added in v0.11.0
type ArtifactsRepo struct {
// contains filtered or unexported fields
}
ArtifactsRepo is the typed accessor for the artifacts table.
func (*ArtifactsRepo) Delete ¶ added in v0.11.0
func (r *ArtifactsRepo) Delete(ctx context.Context, id string) error
Delete removes one artifact row. Deleting a missing id is not an error.
func (*ArtifactsRepo) GetByHash ¶ added in v0.11.0
GetByHash looks up an artifact by (session, content hash).
func (*ArtifactsRepo) ListAll ¶ added in v0.11.0
ListAll returns every artifact grouped by session id, newest first within each session. The TUI calls it once per refresh instead of issuing one query per session.
func (*ArtifactsRepo) ListBySession ¶ added in v0.11.0
ListBySession returns a session's artifacts, newest first.
func (*ArtifactsRepo) Upsert ¶ added in v0.11.0
func (r *ArtifactsRepo) Upsert(ctx context.Context, in NewArtifact) (Artifact, bool, error)
Upsert inserts the artifact unless a row with the same (session_id, content_hash) already exists, in which case the existing row is returned unchanged and created is false. The lookup-then-insert shape mirrors SubagentsRepo.Upsert; the UNIQUE constraint is the backstop for concurrent writers.
type AttentionState ¶
type AttentionState string
AttentionState classifies whether the user needs to act on a session: none, waiting for input, or in an error state.
const ( AttentionNone AttentionState = "none" AttentionWaitingInput AttentionState = "waiting_input" AttentionError AttentionState = "error" )
type Conductor ¶
type Conductor struct {
ID string `db:"id"`
Name string `db:"name"`
ProjectPath string `db:"project_path"`
PlanPath sql.NullString `db:"plan_path"`
Status string `db:"status"`
MasterSessionID sql.NullString `db:"master_session_id"`
CreatedAt time.Time `db:"created_at"`
}
Conductor is the row type for the conductors table.
type ConductorStatus ¶
type ConductorStatus string
ConductorStatus values stored in conductors.status.
const ( ConductorDraft ConductorStatus = "draft" ConductorRunning ConductorStatus = "running" ConductorPaused ConductorStatus = "paused" ConductorDone ConductorStatus = "done" ConductorFailed ConductorStatus = "failed" )
type ConductorTask ¶
type ConductorTask struct {
ID string `db:"id"`
ConductorID string `db:"conductor_id"`
Name string `db:"name"`
Status string `db:"status"`
DependsOn string `db:"depends_on"` // JSON-encoded []string
Prompt string `db:"prompt"`
AssignedSessionID sql.NullString `db:"assigned_session_id"`
StartedAt sql.NullTime `db:"started_at"`
CompletedAt sql.NullTime `db:"completed_at"`
Result sql.NullString `db:"result"`
}
ConductorTask is the row type for the tasks table.
func (ConductorTask) Dependencies ¶
func (t ConductorTask) Dependencies() []string
Dependencies decodes the JSON-encoded depends_on column.
type ConductorsRepo ¶
type ConductorsRepo struct {
// contains filtered or unexported fields
}
ConductorsRepo is the typed accessor for the conductors table and its task / message children.
func (*ConductorsRepo) AssignTask ¶
func (r *ConductorsRepo) AssignTask(ctx context.Context, id, sessionID string) error
AssignTask binds a mosaic session id to a task.
func (*ConductorsRepo) Insert ¶
func (r *ConductorsRepo) Insert(ctx context.Context, in NewConductor) (Conductor, error)
Insert creates a conductor row and returns it.
func (*ConductorsRepo) InsertTask ¶
func (r *ConductorsRepo) InsertTask(ctx context.Context, in NewConductorTask) (ConductorTask, error)
InsertTask inserts a task row.
func (*ConductorsRepo) List ¶
func (r *ConductorsRepo) List(ctx context.Context) ([]Conductor, error)
List returns every conductor in created_at order.
func (*ConductorsRepo) ListTasks ¶
func (r *ConductorsRepo) ListTasks(ctx context.Context, conductorID string) ([]ConductorTask, error)
ListTasks returns every task for a conductor in insertion order.
func (*ConductorsRepo) MarkDelivered ¶
func (r *ConductorsRepo) MarkDelivered(ctx context.Context, sessionID string) error
MarkDelivered marks every undelivered message for a session as delivered now.
func (*ConductorsRepo) PostMessage ¶
func (r *ConductorsRepo) PostMessage(ctx context.Context, in NewMessage) (Message, error)
PostMessage inserts a message row.
func (*ConductorsRepo) SetStatus ¶
func (r *ConductorsRepo) SetStatus(ctx context.Context, id string, status ConductorStatus) error
SetStatus updates the conductor lifecycle column.
func (*ConductorsRepo) SetTaskStatus ¶
func (r *ConductorsRepo) SetTaskStatus(ctx context.Context, id string, status TaskStatus) error
SetTaskStatus updates the lifecycle column on one task.
type Message ¶
type Message struct {
ID int64 `db:"id"`
ConductorID sql.NullString `db:"conductor_id"`
FromSessionID sql.NullString `db:"from_session_id"`
ToSessionID sql.NullString `db:"to_session_id"`
Kind string `db:"kind"`
Body string `db:"body"`
TS time.Time `db:"ts"`
DeliveredAt sql.NullTime `db:"delivered_at"`
}
Message is the row type for the messages table.
type NewArtifact ¶ added in v0.11.0
type NewArtifact struct {
SessionID string
Kind string
Source string
AgentID string
Title string
Content string
Path string
ContentHash string
CreatedAt time.Time
}
NewArtifact is the input shape for ArtifactsRepo.Upsert. CreatedAt should be the transcript timestamp so a replay after restart keeps the original time; zero means now.
type NewConductor ¶
NewConductor is the input shape for ConductorsRepo.Insert.
type NewConductorTask ¶
NewConductorTask is the input shape for ConductorsRepo.InsertTask.
type NewMessage ¶
type NewMessage struct {
ConductorID string
FromSessionID string
ToSessionID string
Kind string
Body string
}
NewMessage is the input shape for ConductorsRepo.PostMessage.
type NewNotification ¶
type NewNotification struct {
SessionID string
Source NotificationSource
Agent string
Event string
Title string
Body string
}
NewNotification is the input shape for NotificationsRepo.Insert.
type NewSession ¶
type NewSession struct {
// ID, when non-empty, is used verbatim as the session's
// ULID instead of minting one in Insert. The only caller
// that pre-generates is SessionService.Create, which needs
// the ID to derive the sandbox container name before the
// row exists. All other callers leave this empty.
ID string
Name string
ProjectPath string
WorktreePath string
Branch string
Tool SessionTool
// SandboxMode records which isolation backend the session
// uses. Defaults to "none" when empty.
SandboxMode string
// SandboxContainer is the container name for docker sessions.
// Empty when SandboxMode != "docker".
SandboxContainer string
}
NewSession is the input shape for SessionsRepo.Insert. Required fields are validated; optional fields default sensibly.
type NewSubagent ¶
type NewSubagent struct {
ParentSessionID string
ClaudeSessionID string
AgentSessionID string
AgentRuntime string
AgentID string
SubagentType string
Name string
Description string
TranscriptPath string
}
NewSubagent is the input shape for SubagentsRepo.Upsert.
type Notification ¶
type Notification struct {
ID int64 `db:"id"`
SessionID string `db:"session_id"`
Source string `db:"source"`
Agent sql.NullString `db:"agent"`
Event sql.NullString `db:"event"`
Title sql.NullString `db:"title"`
Body sql.NullString `db:"body"`
TS time.Time `db:"ts"`
DismissedAt sql.NullTime `db:"dismissed_at"`
}
Notification is the row type for the notifications table.
type NotificationSource ¶
type NotificationSource string
NotificationSource categorises where a notification was observed.
const ( NotificationSourceHook NotificationSource = "hook" NotificationSourceJSONL NotificationSource = "jsonl" NotificationSourceOSC NotificationSource = "osc" )
type NotificationsRepo ¶
type NotificationsRepo struct {
// contains filtered or unexported fields
}
NotificationsRepo is the typed accessor for the notifications table.
func (*NotificationsRepo) Dismiss ¶
func (r *NotificationsRepo) Dismiss(ctx context.Context, sessionID string) error
Dismiss marks every unseen notification for the session as dismissed at the current timestamp.
func (*NotificationsRepo) GetByID ¶
func (r *NotificationsRepo) GetByID(ctx context.Context, id int64) (Notification, error)
GetByID fetches a single notification.
func (*NotificationsRepo) Insert ¶
func (r *NotificationsRepo) Insert(ctx context.Context, in NewNotification) (Notification, error)
Insert records a new notification.
func (*NotificationsRepo) ListUnseen ¶
func (r *NotificationsRepo) ListUnseen(ctx context.Context, sessionID string) ([]Notification, error)
ListUnseen returns notifications without a dismissed_at, ordered most-recent first.
type Session ¶
type Session struct {
ID string `db:"id"`
Name string `db:"name"`
ProjectPath string `db:"project_path"`
WorktreePath string `db:"worktree_path"`
Branch sql.NullString `db:"branch"`
TmuxSession string `db:"tmux_session"`
Tool string `db:"tool"`
Status string `db:"status"`
ClaudeSessionID sql.NullString `db:"claude_session_id"`
AgentSessionID sql.NullString `db:"agent_session_id"`
AgentSessionSource string `db:"agent_session_source"`
AgentSessionPath string `db:"agent_session_path"`
AgentCLIVersion string `db:"agent_cli_version"`
ConductorID sql.NullString `db:"conductor_id"`
CreatedAt time.Time `db:"created_at"`
LastActiveAt time.Time `db:"last_active_at"`
AttentionState string `db:"attention_state"`
AttentionTitle sql.NullString `db:"attention_title"`
AttentionBody sql.NullString `db:"attention_body"`
AttentionSince sql.NullTime `db:"attention_since"`
AttentionSource sql.NullString `db:"attention_source"`
// SandboxMode records the isolation backend the session was
// launched with: "none" (direct host execution) or "docker".
// Persisted so Stop/Delete can issue `docker rm -f` without
// having to re-derive the mode from config on the reattach
// path (where that config may have changed).
SandboxMode string `db:"sandbox_mode"`
// SandboxContainer is the deterministic container name
// (mosaic-<id>) for docker-backed sessions. Empty when
// SandboxMode != "docker". Stored verbatim so cleanup code
// does not depend on how the name was computed.
SandboxContainer string `db:"sandbox_container"`
}
Session is the row representation of a mosaic session.
type SessionMCP ¶
type SessionMCP struct {
SessionID string `db:"session_id"`
MCPName string `db:"mcp_name"`
AttachedAt time.Time `db:"attached_at"`
}
SessionMCP is one row of the session_mcps table: the intent "this mosaic session has MCP <name> attached, since <attached_at>".
type SessionMCPsRepo ¶
type SessionMCPsRepo struct {
// contains filtered or unexported fields
}
SessionMCPsRepo is the typed accessor for session_mcps.
func (*SessionMCPsRepo) Attach ¶
func (r *SessionMCPsRepo) Attach(ctx context.Context, sessionID, mcpName string) error
Attach records that sessionID should have mcpName active. Calling it on an already-attached pair is a no-op (the primary key makes the INSERT fail with a UNIQUE violation; we turn that into success because the desired state already holds).
func (*SessionMCPsRepo) AttachedNames ¶
func (r *SessionMCPsRepo) AttachedNames(ctx context.Context, sessionID string) (map[string]bool, error)
AttachedNames is a convenience that returns only the names of the attached MCPs for sessionID — the shape the TUI modal needs so it can render ☑/☐ next to each discovered server.
func (*SessionMCPsRepo) Detach ¶
func (r *SessionMCPsRepo) Detach(ctx context.Context, sessionID, mcpName string) error
Detach removes an attachment. Detaching something that is not attached is silently a no-op so the UI can toggle freely.
func (*SessionMCPsRepo) ForSession ¶
func (r *SessionMCPsRepo) ForSession(ctx context.Context, sessionID string) ([]SessionMCP, error)
ForSession lists every MCP currently attached to sessionID, sorted by attach time so the UI can surface the most recent additions first if it wants to.
func (*SessionMCPsRepo) IsAttached ¶
IsAttached reports whether a given (session, mcp) pair is currently attached.
type SessionSkill ¶
type SessionSkill struct {
SessionID string `db:"session_id"`
SkillName string `db:"skill_name"`
AttachedAt time.Time `db:"attached_at"`
}
SessionSkill is one row of the session_skills table.
type SessionSkillsRepo ¶
type SessionSkillsRepo struct {
// contains filtered or unexported fields
}
SessionSkillsRepo is the typed accessor for session_skills. Intentionally identical in shape to SessionMCPsRepo: the two tables have the same model (attachment intent keyed by a name) so they share the same CRUD verbs.
func (*SessionSkillsRepo) Attach ¶
func (r *SessionSkillsRepo) Attach(ctx context.Context, sessionID, skillName string) error
Attach records that sessionID should have skillName active. Duplicate attaches are turned into no-ops so the MODIFY path can blindly run it without an explicit "is attached" check.
func (*SessionSkillsRepo) AttachedNames ¶
func (r *SessionSkillsRepo) AttachedNames(ctx context.Context, sessionID string) (map[string]bool, error)
AttachedNames returns a set of skill names attached to sessionID, shaped for the TUI modal so it can check membership in O(1) when rendering the ☑/☐ column.
func (*SessionSkillsRepo) Detach ¶
func (r *SessionSkillsRepo) Detach(ctx context.Context, sessionID, skillName string) error
Detach removes an attachment.
func (*SessionSkillsRepo) ForSession ¶
func (r *SessionSkillsRepo) ForSession(ctx context.Context, sessionID string) ([]SessionSkill, error)
ForSession lists every skill currently attached to sessionID.
func (*SessionSkillsRepo) IsAttached ¶
func (r *SessionSkillsRepo) IsAttached(ctx context.Context, sessionID, skillName string) (bool, error)
IsAttached reports whether a (session, skill) pair is attached.
type SessionStatus ¶
type SessionStatus string
SessionStatus is the value stored in sessions.status.
const ( StatusIdle SessionStatus = "idle" StatusRunning SessionStatus = "running" StatusWaiting SessionStatus = "waiting" StatusError SessionStatus = "error" StatusStopped SessionStatus = "stopped" )
type SessionTool ¶
type SessionTool string
SessionTool is the agent runtime a session is launched with.
const ( ToolClaude SessionTool = "claude" ToolCodex SessionTool = "codex" ToolGemini SessionTool = "gemini" ToolShell SessionTool = "shell" )
type SessionsRepo ¶
type SessionsRepo struct {
// contains filtered or unexported fields
}
SessionsRepo is the typed accessor for the sessions table.
func (*SessionsRepo) BindAgentSession ¶ added in v0.10.0
func (r *SessionsRepo) BindAgentSession(ctx context.Context, id string, runtime SessionTool, agentSessionID, path, cliVersion string) error
BindAgentSession associates an agent runtime's native session id with a mosaic session. Claude writes both the generic fields and the legacy claude_session_id mirror so older integrations keep working.
func (*SessionsRepo) BindClaudeSession ¶ added in v0.7.0
func (r *SessionsRepo) BindClaudeSession(ctx context.Context, id, claudeSessionID string) error
BindClaudeSession associates a Claude Code session id with a mosaic session. Deprecated: use BindAgentSession for new integrations.
func (*SessionsRepo) Delete ¶
func (r *SessionsRepo) Delete(ctx context.Context, id string) error
Delete removes a session row.
func (*SessionsRepo) GetByID ¶
GetByID returns a session by its ULID, or ErrSessionNotFound.
func (*SessionsRepo) GetByName ¶
GetByName returns a session by its user-visible name, or ErrSessionNotFound.
func (*SessionsRepo) Insert ¶
func (r *SessionsRepo) Insert(ctx context.Context, in NewSession) (Session, error)
Insert creates a new session row. The ID and tmux session name are generated automatically; pass NewSession with the user-facing fields populated.
func (*SessionsRepo) List ¶
func (r *SessionsRepo) List(ctx context.Context) ([]Session, error)
List returns all sessions ordered by most recently active first.
func (*SessionsRepo) SetAttention ¶
func (r *SessionsRepo) SetAttention( ctx context.Context, id string, state AttentionState, title, body, source string, ) error
SetAttention records that a session is asking for the user's attention. Pass AttentionNone together with empty title/body to clear it.
func (*SessionsRepo) UpdateStatus ¶
func (r *SessionsRepo) UpdateStatus(ctx context.Context, id string, status SessionStatus) error
UpdateStatus changes the status of a session and refreshes its last_active_at timestamp.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is the top-level handle owning the SQLite database. Repositories (Sessions, Subagents, Worktrees, ...) hang off it via methods so the rest of the codebase can call store.Sessions().Insert(...) etc.
func Open ¶
Open opens the SQLite database at path with the connection settings mosaic requires (WAL journal, foreign keys on, busy timeout). It does NOT run migrations: callers must invoke Store.Migrate explicitly so that mosaic doctor can decide when migrations happen.
func (*Store) AppliedVersions ¶
AppliedVersions returns the set of migration versions currently recorded in schema_migrations.
func (*Store) Artifacts ¶ added in v0.11.0
func (s *Store) Artifacts() *ArtifactsRepo
Artifacts returns the per-session rich-content (artifact) repository.
func (*Store) Close ¶
Close releases the database handle. Repositories must not be used after Close returns.
func (*Store) Conductors ¶
func (s *Store) Conductors() *ConductorsRepo
Conductors returns the conductors / tasks / messages repository.
func (*Store) DB ¶
DB returns the underlying sqlx handle. It exists for tests and for subsystems that need to compose their own queries; production code should prefer the typed repositories.
func (*Store) Migrate ¶
Migrate applies any unapplied migrations from the embedded migrations directory. It is idempotent: re-running it after every migration has already been applied is a no-op.
Each migration is applied inside its own transaction so a failure leaves the database in a known state.
func (*Store) Notifications ¶
func (s *Store) Notifications() *NotificationsRepo
Notifications returns the notifications repository.
func (*Store) SessionMCPs ¶
func (s *Store) SessionMCPs() *SessionMCPsRepo
SessionMCPs returns the session ↔ MCP attachment repository.
func (*Store) SessionSkills ¶
func (s *Store) SessionSkills() *SessionSkillsRepo
SessionSkills returns the session ↔ skill attachment repository.
func (*Store) Sessions ¶
func (s *Store) Sessions() *SessionsRepo
Sessions returns the sessions repository.
func (*Store) Subagents ¶
func (s *Store) Subagents() *SubagentsRepo
Subagents returns the sub-agents repository.
func (*Store) WALCheckpoint ¶ added in v0.4.0
WALCheckpoint forces a WAL checkpoint so the -wal file is truncated and its space reclaimed. This is useful for the `mosaic clean` command.
type Subagent ¶
type Subagent struct {
ID string `db:"id"`
ParentSessionID string `db:"parent_session_id"`
ClaudeSessionID string `db:"claude_session_id"`
AgentSessionID string `db:"agent_session_id"`
AgentRuntime string `db:"agent_runtime"`
AgentID string `db:"agent_id"`
SubagentType string `db:"subagent_type"`
Name sql.NullString `db:"name"`
Description sql.NullString `db:"description"`
Status string `db:"status"`
StartedAt time.Time `db:"started_at"`
CompletedAt sql.NullTime `db:"completed_at"`
TranscriptPath string `db:"transcript_path"`
CurrentTool sql.NullString `db:"current_tool"`
CurrentToolStartedAt sql.NullTime `db:"current_tool_started_at"`
LastEventOffset int64 `db:"last_event_offset"`
}
Subagent is the row type for the subagents table.
func (Subagent) LabelParts ¶ added in v0.7.0
LabelParts reports whether the row carries a meaningful (non-default) type and a non-empty description. Callers use the results to format display labels without duplicating the DefaultSubagentType filter.
type SubagentMeta ¶ added in v0.8.0
SubagentMeta groups the human-facing metadata fields that arrive from the parent transcript's Agent tool_use input. Using a struct prevents call-site argument transposition and makes future field additions backward-compatible.
type SubagentStatus ¶
type SubagentStatus string
SubagentStatus values stored in the subagents.status column.
const ( SubagentSpawning SubagentStatus = "spawning" SubagentRunning SubagentStatus = "running" SubagentCompleted SubagentStatus = "completed" SubagentErrored SubagentStatus = "error" )
type SubagentsRepo ¶
type SubagentsRepo struct {
// contains filtered or unexported fields
}
SubagentsRepo is the typed accessor for the subagents table.
func (*SubagentsRepo) GetByAgentID ¶
func (r *SubagentsRepo) GetByAgentID(ctx context.Context, parentSessionID, agentID string) (Subagent, error)
GetByAgentID looks up a sub-agent by (parent session, agent id).
func (*SubagentsRepo) ListByParent ¶
func (r *SubagentsRepo) ListByParent(ctx context.Context, parentSessionID string) ([]Subagent, error)
ListByParent returns every sub-agent for a parent session, ordered by started_at.
func (*SubagentsRepo) ListRunning ¶ added in v0.5.0
func (r *SubagentsRepo) ListRunning(ctx context.Context) ([]Subagent, error)
ListRunning returns every sub-agent whose status is still "running", across all parent sessions. Used by the reconciler's periodic sweep to find background agents that have gone silent.
func (*SubagentsRepo) MarkCompleted ¶
func (r *SubagentsRepo) MarkCompleted(ctx context.Context, id string) error
MarkCompleted records that a sub-agent finished.
func (*SubagentsRepo) MarkErrored ¶ added in v0.5.0
func (r *SubagentsRepo) MarkErrored(ctx context.Context, id string) error
MarkErrored records that a sub-agent finished with an error.
func (*SubagentsRepo) PromoteSpawning ¶ added in v0.7.0
func (r *SubagentsRepo) PromoteSpawning(ctx context.Context, id string) error
PromoteSpawning transitions a sub-agent from "spawning" to "running" without touching current_tool. This is used when a transcript entry arrives that contains no tool_use block (e.g. plain text), so the status reflects activity even though no tool is active yet.
func (*SubagentsRepo) SetEventOffset ¶
SetEventOffset persists the byte offset of the last event the watcher consumed for this sub-agent. Used to resume after restarts.
func (*SubagentsRepo) SetMetadata ¶
func (r *SubagentsRepo) SetMetadata(ctx context.Context, id string, meta SubagentMeta) error
SetMetadata updates the human-facing metadata for a row. It is called once the reconciler has parsed the parent transcript's `Agent` tool_use/tool_result pair and knows the real values — before that point we only know the agent_id, so rows are inserted with a placeholder type and get filled in when the metadata lands.
Empty values are ignored so repeated calls never blank out fields that another code path already populated.
func (*SubagentsRepo) UpdateRunningTool ¶
func (r *SubagentsRepo) UpdateRunningTool(ctx context.Context, id, toolName string, startedAt time.Time) error
UpdateRunningTool patches the "what is this sub-agent doing right now?" columns. Pass an empty toolName to clear them.
The WHERE clause guards against late transcript entries flipping a sub-agent that has already reached a terminal state back to "running": once MarkCompleted / MarkErrored has run, stray tool_use/tool_result blocks in the child transcript must not resurrect the row.
func (*SubagentsRepo) Upsert ¶
func (r *SubagentsRepo) Upsert(ctx context.Context, in NewSubagent) (Subagent, error)
Upsert inserts a sub-agent if it does not exist, otherwise returns the existing row. Sub-agents are uniquely identified by the (parent_session_id, agent_id) pair.
type TaskStatus ¶
type TaskStatus string
TaskStatus values stored in tasks.status.
const ( TaskPending TaskStatus = "pending" TaskReady TaskStatus = "ready" TaskRunning TaskStatus = "running" TaskDone TaskStatus = "done" TaskFailed TaskStatus = "failed" )