store

Documentation

Overview

Package store manages Aviary's file-based data directory.

Index

• Constants
• func AgentDir(agentID string) string
• func AgentRulesPath(agentID string) string
• func AllJobDirs() []string
• func AllTaskCompileDirs() []string
• func AppendJSONL(path string, v any) error
• func BrowserMediaDir() string
• func CheckpointDir(agentID string) string
• func CheckpointPath(agentID, checkpointID string) string
• func DataDir() string
• func DeleteAgentFile(agentID, file string) error
• func DeleteJSON(path string) error
• func EnsureAgentTemplate(agentID string) error
• func EnsureDirs() error
• func EnsureNewAgentTemplates(prev, next *config.Config) error
• func EnsureSessionChannel(agentID, sessionID, channelType, configuredID, channelID string) error
• func EnsureSessionChannelTarget(agentID, sessionID string, target SessionChannel) error
• func FindJobPath(id string) string
• func FindSessionPath(agentID, sessionID string) string
• func FindTaskCompilePath(id string) string
• func IncomingMediaDir(channelType string) string
• func JobPath(agentID, id string) string
• func ListAgentFiles(agentID string) ([]string, error)
• func ListJSON[T any](dir string, suffix string) ([]T, error)
• func MediaDir() string
• func NotesPath(_ string) string
• func OutgoingMediaDir(channelType string) string
• func ReadAgentFile(agentID, file string) (string, error)
• func ReadJSON[T any](path string) (T, error)
• func ReadJSONL[T any](path string) ([]T, error)
• func RenameMatchingAgentDirs(prev, next *config.Config) error
• func RewriteJSONL[T any](path string, entries []T) error
• func ScreenshotDir() string
• func SessionChannelsPath(agentID, sessionID string) string
• func SessionMetaPath(agentID, sessionID string) string
• func SessionPath(agentID, sessionID string) string
• func SetDataDir(dir string)
• func SetSessionChannel(agentID, sessionID, channelType, configuredID, channelID string) error
• func SetSessionChannelTarget(agentID, sessionID string, target SessionChannel) error
• func SetWorkspaceDir(dir string)
• func StatePath() string
• func StripMarkdownCommentLines(content string) string
• func SubDir(name string) string
• func SyncAgentTemplate(agentID string) error
• func TaskCompilePath(agentID, id string) string
• func UpdateChannelMetadataState(prevCfg, nextCfg *config.Config, now time.Time) error
• func UsagePath() string
• func WorkspaceDir() string
• func WriteAgentFile(agentID, file, content string) error
• func WriteAppState(state *AppState) error
• func WriteJSON(path string, v any) error
• func WriteSessionChannels(cfg *SessionChannelsConfig) error
• func WriteSessionMeta(path string, meta SessionMeta) error
• type AppState
  • func ReadAppState() (*AppState, error)
• type ChannelMetadata
• type ConversationMeta
• type SessionChannel
• type SessionChannelsConfig
  • func FindAllSessionChannelsConfigs() ([]*SessionChannelsConfig, error)
  • func ReadSessionChannels(agentID, sessionID string) (*SessionChannelsConfig, error)
• type SessionMeta
  • func ReadSessionMeta(path string) (SessionMeta, error)

Constants

const (
	DirAgents = "agents" // per-agent subdirectories
	DirCerts  = "certs"
	DirAuth   = "auth"
	DirMedia  = "media"
	DirUsage  = "usage"

	// Deprecated: legacy flat directories kept for backward-compat migration.
	DirJobs     = "jobs"     // deprecated: jobs now live under agents/<name>/jobs/
	DirSessions = "sessions" // deprecated: sessions now live under agents/<name>/sessions/
)

Top-level directory name constants under DataDir().

Functions

func AgentDir

func AgentDir(agentID string) string

AgentDir returns the per-agent directory path: <datadir>/agents/<name>/.

func AgentRulesPath

func AgentRulesPath(agentID string) string

AgentRulesPath returns the path for an agent's RULES.md file.

func AllJobDirs

func AllJobDirs() []string

AllJobDirs returns all existing agents/<name>/jobs/ directory paths, plus the legacy jobs/ directory if it exists, for bulk job enumeration.

func AllTaskCompileDirs

func AllTaskCompileDirs() []string

AllTaskCompileDirs returns all existing agents/<name>/task_compiles/ directory paths for bulk compile record enumeration.

func AppendJSONL

func AppendJSONL(path string, v any) error

AppendJSONL marshals v as a single JSON line and appends it to path. The file (and any parent directories) are created if they do not exist.

func BrowserMediaDir

func BrowserMediaDir() string

BrowserMediaDir returns the directory where browser screenshots are saved. Browser artifacts are global resources (browser is not per-agent).

func CheckpointDir

func CheckpointDir(agentID string) string

CheckpointDir returns the directory where pending run checkpoints are stored for an agent: <datadir>/agents/<agentID>/checkpoints/.

func CheckpointPath

func CheckpointPath(agentID, checkpointID string) string

CheckpointPath returns the path for a specific run checkpoint file: <datadir>/agents/<agentID>/checkpoints/<checkpointID>.json.

func DataDir

func DataDir() string

DataDir returns the Aviary data directory. Resolution order: SetDataDir value > XDG_CONFIG_HOME > ~/.config/aviary.

func DeleteAgentFile

func DeleteAgentFile(agentID, file string) error

DeleteAgentFile deletes a file from an agent directory. Root-level protected files (AGENTS.md, MEMORY.md, RULES.md, SYSTEM.md) cannot be deleted.

func DeleteJSON

func DeleteJSON(path string) error

DeleteJSON removes a JSON file.

func EnsureAgentTemplate

func EnsureAgentTemplate(agentID string) error

EnsureAgentTemplate is a compatibility wrapper for older callers.

func EnsureDirs

func EnsureDirs() error

EnsureDirs creates all required data subdirectories.

func EnsureNewAgentTemplates

func EnsureNewAgentTemplates(prev, next *config.Config) error

EnsureNewAgentTemplates syncs the embedded scaffold for agents that are present in next but absent from prev.

func EnsureSessionChannel

func EnsureSessionChannel(agentID, sessionID, channelType, configuredID, channelID string) error

EnsureSessionChannel adds channelType/configuredID/channelID to the session's channel config if it is not already present, then writes the file. It is a no-op when the channel target is already listed.

func EnsureSessionChannelTarget

func EnsureSessionChannelTarget(agentID, sessionID string, target SessionChannel) error

EnsureSessionChannelTarget adds target to the session's channel config if it is not already present, or updates the existing target when thread metadata changes.

func FindJobPath

func FindJobPath(id string) string

FindJobPath scans all known agent directories and returns the full path for the first job file matching id. Returns "" when not found.

func FindSessionPath

func FindSessionPath(agentID, sessionID string) string

FindSessionPath locates the .jsonl file for sessionID under the given agent. Returns "" when not found.

func FindTaskCompilePath

func FindTaskCompilePath(id string) string

FindTaskCompilePath scans all known agent directories and returns the full path for the first task compile record matching id. Returns "" when not found.

func IncomingMediaDir

func IncomingMediaDir(channelType string) string

IncomingMediaDir returns the directory where inbound channel media is saved.

func JobPath

func JobPath(agentID, id string) string

JobPath returns the path for a job file under the agent's jobs directory: <datadir>/agents/<agentID>/jobs/<id>.json.

func ListAgentFiles

func ListAgentFiles(agentID string) ([]string, error)

ListAgentFiles returns all files under an agent directory, recursively including subdirectories. Returned paths are slash-delimited and relative to the agent dir.

func ListJSON

func ListJSON[T any](dir string, suffix string) ([]T, error)

ListJSON returns all values in dir whose file names match the given suffix. Typically called with suffix=".json".

func MediaDir

func MediaDir() string

MediaDir returns the root directory for persisted media artifacts.

func NotesPath

func NotesPath(_ string) string

NotesPath returns the path for the human-editable markdown notes file in the current workspace directory.

func OutgoingMediaDir

func OutgoingMediaDir(channelType string) string

OutgoingMediaDir returns the directory where outbound channel media is saved.

func ReadAgentFile

func ReadAgentFile(agentID, file string) (string, error)

ReadAgentFile reads a file from an agent directory. file must be a relative path beneath the agent directory.

func ReadJSON

func ReadJSON[T any](path string) (T, error)

ReadJSON reads and unmarshals a JSON file into v.

func ReadJSONL

func ReadJSONL[T any](path string) ([]T, error)

ReadJSONL reads all JSON lines from path and returns them as a slice.

func RenameMatchingAgentDirs

func RenameMatchingAgentDirs(prev, next *config.Config) error

RenameMatchingAgentDirs renames on-disk agent directories for agents whose config changed only by name between prev and next. Ambiguous matches are ignored, and genuinely new agents are left for template sync.

func RewriteJSONL

func RewriteJSONL[T any](path string, entries []T) error

RewriteJSONL overwrites path with the given entries (used by compactor).

func ScreenshotDir

func ScreenshotDir() string

ScreenshotDir returns the directory where browser screenshots are saved. Deprecated: use BrowserMediaDir.

func SessionChannelsPath

func SessionChannelsPath(agentID, sessionID string) string

SessionChannelsPath returns the path for the session's channel delivery config file: <datadir>/agents/<agentID>/sessions/<sessionID>.channels.json. It shares the same naming logic as SessionPath.

func SessionMetaPath

func SessionMetaPath(agentID, sessionID string) string

SessionMetaPath returns the path for the sidecar metadata file for a session. It mirrors SessionPath but uses a .meta.json extension.

func SessionPath

func SessionPath(agentID, sessionID string) string

SessionPath returns the path for the given session file under the agent's sessions directory: <datadir>/agents/<agentID>/sessions/<sessionID>.jsonl.

func SetDataDir

func SetDataDir(dir string)

SetDataDir overrides the directory returned by DataDir. Pass an empty string to restore automatic resolution via XDG_CONFIG_HOME or ~/.config. This is intended for the --data-dir CLI flag and for tests.

func SetSessionChannel

func SetSessionChannel(agentID, sessionID, channelType, configuredID, channelID string) error

SetSessionChannel replaces the session's delivery config with a single target.

func SetSessionChannelTarget

func SetSessionChannelTarget(agentID, sessionID string, target SessionChannel) error

SetSessionChannelTarget replaces the session's delivery config with a single target.

func SetWorkspaceDir

func SetWorkspaceDir(dir string)

SetWorkspaceDir overrides the directory returned by WorkspaceDir. Pass an empty string to restore automatic resolution via the process working directory. This is intended for tests and tools that need repo-local artifacts.

func StatePath

func StatePath() string

StatePath returns the on-disk location for Aviary runtime metadata.

func StripMarkdownCommentLines

func StripMarkdownCommentLines(content string) string

StripMarkdownCommentLines removes HTML comment blocks from markdown when the content is being fed back into prompts or prompt-adjacent tools.

func SubDir

func SubDir(name string) string

SubDir returns the full path to a named subdirectory under DataDir.

func SyncAgentTemplate

func SyncAgentTemplate(agentID string) error

SyncAgentTemplate merges the embedded agent scaffold into an agent directory. Files that do not yet exist are created. Existing files are never deleted or replaced wholesale; for markdown files, only the "Synced by Aviary" section is updated when present in both source and destination.

func TaskCompilePath

func TaskCompilePath(agentID, id string) string

TaskCompilePath returns the path for a task compile record under the agent's task_compiles directory: <datadir>/agents/<agentID>/task_compiles/<id>.json.

func UpdateChannelMetadataState

func UpdateChannelMetadataState(prevCfg, nextCfg *config.Config, now time.Time) error

UpdateChannelMetadataState updates per-channel lifecycle timestamps in state.json.

func UsagePath

func UsagePath() string

UsagePath returns the path to the global usage log file.

func WorkspaceDir

func WorkspaceDir() string

WorkspaceDir returns the current workspace root. Resolution order: SetWorkspaceDir value > process working directory.

func WriteAgentFile

func WriteAgentFile(agentID, file, content string) error

WriteAgentFile creates or replaces a file under an agent directory. file may be a relative path including subdirectories (e.g. notes/foo.txt).

func WriteAppState

func WriteAppState(state *AppState) error

WriteAppState persists runtime metadata to disk.

func WriteJSON

func WriteJSON(path string, v any) error

WriteJSON marshals v and atomically writes it to path. The write is atomic: data is written to a temp file then renamed. Parent directories are created if they do not exist.

func WriteSessionChannels

func WriteSessionChannels(cfg *SessionChannelsConfig) error

WriteSessionChannels persists the channel delivery config for a session.

func WriteSessionMeta

func WriteSessionMeta(path string, meta SessionMeta) error

WriteSessionMeta atomically writes meta to path.

Types

type AppState

type AppState struct {
	Channels map[string]ChannelMetadata `json:"channels,omitempty"`
}

AppState stores runtime metadata that should not live in aviary.yaml.

func ReadAppState

func ReadAppState() (*AppState, error)

ReadAppState loads runtime metadata from disk, returning an empty state if absent.

type ChannelMetadata

type ChannelMetadata struct {
	EnabledAt  time.Time `json:"enabled_at,omitempty"`
	DisabledAt time.Time `json:"disabled_at,omitempty"`
}

ChannelMetadata stores lifecycle timestamps for a configured channel.

type ConversationMeta

type ConversationMeta struct {
	ID         string    `json:"id"`
	LastUsedAt time.Time `json:"last_used_at"`
}

ConversationMeta holds the provider-native conversation ID for a session and when it was last used. Providers that support server-side history (e.g. the OpenAI Responses API) populate this so subsequent requests can pass only the new user turn instead of replaying the full message history.

type SessionChannel

type SessionChannel struct {
	Type         string `json:"type"`                    // e.g. "signal", "slack"
	ConfiguredID string `json:"configured_id,omitempty"` // configured channel instance ID from agent config
	ID           string `json:"id"`                      // channel/conversation target ID (phone number, Slack channel ID, etc.)
	ThreadTS     string `json:"thread_ts,omitempty"`     // optional platform thread/root timestamp for threaded delivery
}

SessionChannel represents a delivery target for a session's responses.

type SessionChannelsConfig

type SessionChannelsConfig struct {
	SessionID string           `json:"session_id"`
	AgentID   string           `json:"agent_id"`
	Channels  []SessionChannel `json:"channels"`
}

SessionChannelsConfig is the content of a session's .channels.json sidecar file. It records which channels should receive outgoing responses for that session.

func FindAllSessionChannelsConfigs

func FindAllSessionChannelsConfigs() ([]*SessionChannelsConfig, error)

FindAllSessionChannelsConfigs scans every agent's sessions directory and returns all existing session channel configs.

func ReadSessionChannels

func ReadSessionChannels(agentID, sessionID string) (*SessionChannelsConfig, error)

ReadSessionChannels reads the channel delivery config for a session. Returns an empty config (not an error) when the file does not exist yet.

type SessionMeta

type SessionMeta struct {
	Conversation *ConversationMeta `json:"conversation,omitempty"`
}

SessionMeta is the sidecar metadata stored alongside a session JSONL file.

func ReadSessionMeta

func ReadSessionMeta(path string) (SessionMeta, error)

ReadSessionMeta loads the sidecar metadata for a session. Returns a zero SessionMeta (not an error) when the file does not exist.