store

package
v0.54.2 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 30 Imported by: 0

Documentation

Overview

Package store is the single-file SQLite core store for personal sessions: sessions, a linear entry log, turns (agentcore run state) and events.

Index

Constants

View Source
const (
	// BucketCold is the session's first call: the provider has nothing cached
	// for it.
	BucketCold = "cold"
	// BucketSegmentStart is the first call after a segment break: compaction
	// wrote a handoff package and the request starts from the new segment.
	BucketSegmentStart = "segment_start"
	// BucketAfterFold is the first call after old tool results were folded or
	// the prefix changed some other way (a truncation, a loaded deferred tool, a
	// changed system prompt, a rewritten message).
	BucketAfterFold = "after_fold"
	// BucketSteady is a call whose request only extends the previous one inside
	// a running segment: the bucket the 95% target is about.
	BucketSteady = "steady"
	// BucketHandoff is a side call that writes a handoff package
	// (attrs.purpose=compact): it sends its own prompt, not the conversation.
	BucketHandoff = "handoff"
	// BucketResume is the first call of a new process that resumed the session
	// inside the same segment (prefix=first, no segment break in between) without
	// a persisted request fingerprint (a session recorded before it existed):
	// `suga run --resume` from gofer and the per-turn processes of the eval land
	// here when nothing was persisted to compare with.
	BucketResume = "resume"
	// BucketResumeSame is that first call when the persisted fingerprint of the
	// previous process is a prefix of it: the request was only appended to, so a
	// provider cache that still holds the session serves it like a steady call.
	BucketResumeSame = "resume_same"
	// BucketResumeChanged is that first call when the persisted fingerprint
	// differs (system prompt, tool table or an earlier message): the prefix has
	// to be sent again however warm the cache is.
	BucketResumeChanged = "resume_changed"
	// BucketProviderSwitch is a call the previous main-loop call's cache cannot
	// serve because another model or provider answered it: the model attr changed,
	// the pool fell back to the next provider, or a model_switch session event lies
	// in between. The request bytes only grow (fold/rewrite would be needed to
	// change them), so without this bucket such a call reads as steady.
	BucketProviderSwitch = "provider_switch"
	// BucketUnknown is a call the trace cannot classify; today only kept for a
	// prefix reason this code does not know.
	BucketUnknown = "unknown"
)

Cache buckets: one class per model call, decided by what happened to the request prefix since the session's previous main-loop call. A provider prompt cache serves the prefix it already saw, so a call that only extends the conversation reuses most of the prompt (steady) while a prefix break has to be sent again (the handoff package of a new segment, old tool results folded, a loaded deferred tool, a changed system prompt). The steady bucket is the one the 95% hit target is about; see docs/research for the definition and the measured numbers.

View Source
const (
	// MetaOrigin is the session meta key holding the entry point.
	MetaOrigin = "origin"
	// OriginChat is an interactive `suga chat`, OriginRun a one-shot
	// `suga run`, OriginACP a session an editor created over ACP,
	// OriginAgent a sub-agent session and OriginSDK an embedded SDK session.
	OriginChat  = "chat"
	OriginRun   = "run"
	OriginACP   = "acp"
	OriginAgent = "agent"
	OriginSDK   = "sdk"
	// MetaPinned marks a session that an embedding host still references. GC
	// treats a JSON boolean true as a keep-forever marker until it is cleared.
	MetaPinned = "pinned"
	// MetaUsedInteractively marks a session created by a non-interactive entry
	// point that a chat continued afterwards: from then on it counts as
	// interactive.
	MetaUsedInteractively = "used_interactively"
)

Session origins (meta.origin). A session records which entry point created it, and `suga data gc --retention` picks the retention period from that: an interactive chat is worth keeping much longer than a session a batch job or an editor integration started (design 0.3, 会话来源).

View Source
const (
	MetaKind          = "kind"
	KindAgent         = "agent"
	MetaParentSession = "parent_session_id"
)

Sub-agent sessions: a session a sub-agent ran in carries meta kind "agent" and the id of the session that started it. They are kept out of session lists and searches (they belong to their parent), counted in the parent's cumulative usage (SumUsageTree) and removed with the parent (gc).

View Source
const (
	// DefaultToolBodyInlineBytes is store.body_inline_bytes: entry JSON
	// above this many bytes moves to the session file. 0 keeps everything inline.
	DefaultToolBodyInlineBytes int64 = 1024
	// BodyFileName is the current append-only file of one session's moved bodies.
	BodyFileName = "bodies.jsonl"
	// LegacyBodyFileName is the v0.36 file name. A ledger v0.40 never renamed still
	// writes it, so a suga of the previous version running next to this one keeps
	// reading its own files; the reader tries both names. (v0.38 dropped the
	// ToolBodyFileName alias of it.)
	LegacyBodyFileName = "tools.jsonl"
)
View Source
const (
	SessionOpen     = "open"
	SessionRunning  = "running"
	SessionArchived = "archived"
)

Session lifecycle states stored in sessions.status.

View Source
const (
	TurnRunning   = "running"
	TurnCompleted = "completed"
	TurnFailed    = "failed"
	TurnCancelled = "cancelled"
)

Turn lifecycle states stored in turns.status.

View Source
const (
	EntryUser          = "user"
	EntryAssistant     = "assistant"
	EntryTool          = "tool"
	EntryCompaction    = "compaction"
	EntryPlan          = "plan"
	EntryHandoff       = "handoff"
	EntryContextUpdate = "context_update"
	// EntryAdmit is the ledger row of one tool call with side effects, written
	// before the call runs (issue suga-r72b): an interrupted turn finds an
	// admitted call without a tool result and answers it as "state unknown"
	// instead of replaying it. It is never a model message.
	EntryAdmit = "admit"
	// EntryRewind marks a conversation rewind (session rewind design 0.2): its
	// JSON is {cut_seq, target_turn, scope, files}. The entries with a seq inside
	// (cut_seq, this record's seq) are masked for the readers that build model
	// context; nothing is deleted and no seq is reused.
	EntryRewind = "rewind"
)

Entry types stored in entries.type. A context_update records what changed inside a segment (rules, append prompt, environment, a missing memory index); it belongs to a turn, is adopted with it and is replayed as a user message at its seq until the next segment record supersedes it.

View Source
const (
	EventModel      = "model"
	EventTool       = "tool"
	EventDenial     = "denial"
	EventTurn       = "turn"
	EventCompaction = "compaction"
	EventToolSearch = "tool_search"
	// EventTurnContext records what a turn starts with (model, mode, tool
	// set, rules/memory snapshot hashes, taint); see D9.
	EventTurnContext = "turn_context"
	// EventSchedule records a host scheduler event (chat idle consolidation:
	// name = task name, status and attrs.event = what happened).
	EventSchedule = "schedule"
	// EventFold records a history folding boundary move: attrs boundary,
	// steps, chars_before and chars_after of the request view.
	EventFold = "fold"
	// EventContext records what the first model request of a turn is made
	// of: chars per part (system prompt, tools, segment context parts,
	// history, hook context, the turn's input) and the window.
	EventContext = "context"
	// EventContextCleared records a --clear-ctx segment break: the session
	// started its next turn on an empty segment (attrs dropped_messages,
	// est_tokens, first_kept_seq, segment). The old entries stay in the log and
	// stay searchable; only the next turn's context stops at the new record.
	EventContextCleared = "context_cleared"
	// EventHook records a run of the user's hook command: name = hook event,
	// attrs decision, additional_chars, notice.
	EventHook = "hook"
	// EventTask records the end of a background task: name = task id, attrs
	// arg (the command), exit_code, bytes, lines, ref, truncated; started_at
	// and duration cover the task's whole run.
	EventTask = "task"
	// EventSession records a change of the session's own lifecycle, outside any
	// turn: name "recovered" is a session left running by a process that died
	// mid-turn taken back to open (attrs previous_status, stale_ms, turn_status),
	// name "session_cwd_changed" a session continued in another working directory
	// than the one it was created in (attrs from, to).
	EventSession = "session"
	// EventSteer records one message a person typed into a running turn
	// (steering): name "delivered" is a steer a model request carried (attrs
	// steer_id, source, chars, step), "returned" one the turn handed back
	// (attrs steer_id, source, chars, reason, disposition), "withdrawn" one the
	// person took back before a request carried it (attrs steer_id, source,
	// chars, count).
	EventSteer = "steer"
	// EventAddDir records a change of the session's added directories
	// (--add-dir) outside any turn: name "add" or "remove", attrs path, mode
	// (ro/rw) and from (keyboard: typed in chat; ask: authorized at an
	// outside-directory question). It is how a trace shows who widened the
	// session's reach and when; chat's :add-dir/:rm-dir and the authorization
	// write it.
	EventAddDir = "add_dir"
	// EventLocalCommand records one local command a person typed at the chat
	// prompt ("!cmd"/"!!cmd") outside any turn: name "run", attrs command (the
	// command, redacted), exit_code, bytes (the output the command wrote),
	// sent (true: the result goes to the model with the next message),
	// cancelled and timeout. It is how a trace shows what was run outside the
	// model's turn; chat writes it.
	EventLocalCommand = "local_command"
	// EventBudget records a budget threshold or accounting warning. Its attrs
	// carry scope, limits, usage, remaining amounts and the reason.
	EventBudget = "budget"
	// EventUndo records a user rollback; its attrs include the file outcome
	// counts and the seq of the deferred suga.undo entry when available.
	EventUndo = "undo"
	// EventVerify records one run of the --verify delivery check (suga run
	// --verify): name "run", attrs round (0 = the first check), exit, duration_ms,
	// output_len (everything the command wrote) and passed.
	EventVerify = "verify"
	// EventNudge records a hit of the "stopped too early" rules
	// (personal.CheckNudge): name "turn", attrs rule (N1/N2), action (pushed: an
	// injected turn follows; hinted: chat only showed a line; recorded: ACP only
	// wrote the trace) and evidence (what the rule found).
	EventNudge = "nudge"
	// EventOutputSchema records one check of the output contract (suga run
	// --output-schema): name "check", attrs round (1 = the first answer, 2 = the
	// correction round), action (ok/corrected/failed), passed, source
	// (whole/fenced/substring/no_json), errors (at most 5 "path: message") and the
	// schema's hash and size - never the schema itself.
	EventOutputSchema = "output_schema"
	// EventLoopGuard records one reminder the loop guard appended to a repeated
	// tool call's result: name = tool, attrs rule (R1 consecutive / R2 total
	// repeats within a turn) and count (which call of the group it was).
	EventLoopGuard = "loop_guard"
	// EventToolInterrupted records a tool call with side effects that a turn
	// ended before storing its result: name = tool, status "interrupted",
	// attrs invocation_id and call_id. The next turn's replay answers the call
	// as "state unknown" instead of running it again.
	EventToolInterrupted = "tool_interrupted"
)

Event kinds stored in events.kind.

View Source
const FTSShrinkPendingNotice = "" /* 129-byte string literal not displayed */

FTSShrinkPendingNotice is the note a search result carries while the ledger still holds tool rows in the index: a search also matches tool output that the new index no longer covers, so "not found" would be read too strongly.

View Source
const GCDefaultOrphanEventRetention = 30 * 24 * time.Hour

GCDefaultOrphanEventRetention is how long the events of a session that no longer exists are kept before `gc --retention --apply` drops them.

View Source
const ImageDirName = "images"

ImageDirName is the directory of a session's images; api.ImagePart.Ref is a slash-separated path below it, relative to the session directory (images/<sha256>.<ext>).

View Source
const ResultSameAsContentKey = "ResultSameAsContent"

ResultSameAsContentKey is the top-level key that marks a stored tool message whose ToolResult.Content was omitted because it equals Content. api.Message reads it on decode (see its UnmarshalJSON).

View Source
const SteadyLowHitBelow = 0.90

SteadyLowHitBelow is the per-call hit rate under which a steady call is listed as a low hit (the target inside one context is higher, see BucketSteady).

Variables

View Source
var (
	// ErrSessionNotFound is returned when a session id does not exist.
	ErrSessionNotFound = errors.New("session not found")
	// ErrTurnNotFound is returned when a turn id does not exist.
	ErrTurnNotFound = errors.New("turn not found")
)
View Source
var ErrToolBodyMissing = errors.New("tool body missing")

ErrToolBodyMissing is returned when a stub's body cannot be read back: the file is gone, the record is shorter than the stub says, or its seq/sha256 does not match. The reader never falls back to the stub's preview (D4).

Functions

func CheckIntegrity

func CheckIntegrity(ctx context.Context, db *sql.DB) error

CheckIntegrity verifies a staged SQLite database before it can replace the user's live store.

func DatabaseFileBytes

func DatabaseFileBytes(path string) int64

DatabaseFileBytes is the size of the database file path plus its -wal and -shm side files, the number that matters for the free-space check: a VACUUM writes a new file of about the main size while the old one still exists.

func EncodeMessage

func EncodeMessage(m api.Message) ([]byte, error)

EncodeMessage encodes a message for an entries row. A tool message whose ToolResult repeats its Content is stored once, with the ResultSameAsContent marker; every other message is encoded exactly as json.Marshal encodes it, so the stored bytes of everything else (and of the provider replay) are untouched.

func FreeDiskSpace

func FreeDiskSpace(path string) (uint64, error)

FreeDiskSpace returns the bytes a caller may still write on the volume that path lives on (the free space available to this user, which is what a temporary VACUUM file of the same size needs).

func HandoffReuseKey added in v0.51.0

func HandoffReuseKey(value string) string

HandoffReuseKey is the aggregation key of a handoff_reuse value: the value itself, or its reason when it carries a detail suffix (fallback:prefix_changed :msg:12 names where the rebuilt request differs, which the aggregate counts with the plain reason).

func ImageExtension

func ImageExtension(mediaType string) string

ImageExtension returns the stored-file extension of a media type (".bin" for an unknown one, which the image tools never produce).

func ImageRef

func ImageRef(sha, mediaType string) string

ImageRef returns the reference of an image part: images/<sha256>.<ext>.

func InteractiveSession

func InteractiveSession(sess Session) bool

InteractiveSession reports whether the retention rules count a session as interactive: created by a chat, continued by a chat, or created before meta.origin existed. A historical session is deliberately treated as interactive, that is as the class with the longer period.

func IsAgentSession

func IsAgentSession(sess Session) bool

IsAgentSession reports whether a sub-agent ran in the session.

func IsDuplicateKey

func IsDuplicateKey(err error) bool

IsDuplicateKey reports whether err is a primary-key or unique constraint violation, i.e. the id of the inserted row is already taken. A caller that generated the id can retry the insert with a fresh one; every other error is returned as is.

func MediaTypeForRef

func MediaTypeForRef(ref string) string

MediaTypeForRef returns the media type of a stored image by its file extension ("" when the extension is not one of the stored formats).

func ParentSession

func ParentSession(sess Session) string

ParentSession is the session that started a sub-agent session ("" for others).

func Percentile

func Percentile(vals []int64, p float64) int64

Percentile returns the p-th percentile (0<p<=100) of vals by the nearest-rank method: the value at 1-based rank ceil(p/100*n) of the sorted data. Empty input yields 0. vals is not modified.

func PinnedSession added in v0.52.0

func PinnedSession(sess Session) bool

PinnedSession reports whether an embedding host has kept a durable reference to the session. It is deliberately independent of the session origin.

func RestoreMessageJSON

func RestoreMessageJSON(raw []byte) []byte

RestoreMessageJSON returns a stored entry's JSON in the shape it had before the tool-result dedupe: an entry carrying the ResultSameAsContent marker is decoded (which restores ToolResult.Content) and encoded again the plain way; any other entry is returned as it is. Readers that hand stored JSON to the outside, such as `suga inspect export`, use it so the dedupe stays a storage detail.

func SessionImagesDir

func SessionImagesDir(sessionsDir, sessionID string) string

SessionImagesDir is the images directory of one session.

func SessionOrigin

func SessionOrigin(sess Session) string

SessionOrigin returns the meta.origin of a session. It is empty for a session created before the key existed (by an older suga).

func SessionUsedInteractively

func SessionUsedInteractively(sess Session) bool

SessionUsedInteractively reports whether a chat continued a session that a non-interactive entry point created (meta.used_interactively).

func StoreImage

func StoreImage(imagesDir string, data []byte, mediaType string) (api.ImagePart, error)

StoreImage writes one picture into imagesDir (a session's images directory) under its content-addressed name and returns the part that names it (Ref, SHA256, MediaType) without any bytes. It is the same atomic write AppendMessages does, exposed for a sender that fills the directory of another session (`suga send --image`): a file of the same sha256 is not written again.

Types

type AgentStorage

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

AgentStorage implements api.Storage on top of the core store with run_id == turn_id: SaveRun/LoadRun use turns.state_json, and messages are session entries tagged with the turn id.

The turn row must exist before SaveRun/AppendMessages (the Runner creates it first); a run id without a turn is reported as ErrTurnNotFound.

func (*AgentStorage) AppendMessages

func (a *AgentStorage) AppendMessages(ctx context.Context, runID string, msgs ...api.Message) error

AppendMessages writes the batch as user/assistant/tool entries of the turn's session in one transaction.

func (*AgentStorage) LoadMessages

func (a *AgentStorage) LoadMessages(ctx context.Context, runID string) ([]api.Message, error)

LoadMessages returns the turn's messages in seq order. An unknown turn is a storage miss; a known turn with no messages yet returns an empty slice.

func (*AgentStorage) LoadRun

func (a *AgentStorage) LoadRun(ctx context.Context, runID string) (*api.RunState, error)

LoadRun returns the saved snapshot. A missing turn or a turn without a saved snapshot is a storage miss (os.ErrNotExist), which agentcore treats as "start a fresh run" (see isStorageMiss in runtime.go).

func (*AgentStorage) SaveRun

func (a *AgentStorage) SaveRun(ctx context.Context, state *api.RunState) error

SaveRun upserts the RunState snapshot into the turn's state_json, without Messages: they are already the turn's session entries (AppendMessages), and a resumed run rebuilds them from there (agentcore.LoadRunAuthority replaces state.Messages with LoadMessages). Storing them twice doubled the database. Old rows that still carry Messages load unchanged.

func (*AgentStorage) WithSessionsDir

func (a *AgentStorage) WithSessionsDir(dir string) *AgentStorage

WithSessionsDir makes AppendMessages write image files below <dir>/<session_id>/images. Without it images are stored with their reference only (the bytes are memory-only anyway, so they are not recoverable).

type BodyRef

type BodyRef struct {
	Off    int64
	Len    int64
	SHA256 string
}

BodyRef is where one moved body lives: the raw entry JSON at Off, Len bytes long, with SHA256 over those bytes.

func (BodyRef) Empty

func (r BodyRef) Empty() bool

Empty reports whether the ref points nowhere (an inline row).

func (BodyRef) String

func (r BodyRef) String() string

String is the entries.body_ref column form.

type CacheBucketStat

type CacheBucketStat struct {
	Bucket       string  `json:"bucket"`
	Calls        int     `json:"calls"`
	InputTokens  int64   `json:"input_tokens"`
	CacheRead    int64   `json:"cache_read_tokens"`
	CacheWrite   int64   `json:"cache_write_tokens"`
	CacheHitRate float64 `json:"cache_hit_rate"`
	// CacheReported is false when no call of the bucket reported cache
	// read/write: a provider without cache then shows "-" instead of 0%.
	CacheReported bool `json:"cache_reported"`
	// PrefixTokens is the summed estimated cacheable prefix of the calls' previous
	// requests (tokens) and PrefixReuseRate = cache read / that: of what the
	// provider could have served from its cache, how much it did serve. Unlike the
	// hit rate it does not depend on how much a call added, so the steady 95%
	// target is measured with it (docs/research/2026-10-26-cache-hit-buckets.md).
	// A provider serving more than the estimate is counted as 100%, not more.
	PrefixTokens int64   `json:"prefix_reused_tokens"`
	PrefixReuse  float64 `json:"prefix_reuse_rate"`
	// Reasons counts the calls of a prefix-change bucket by cause (system, tools,
	// fold, segment, rewrite): what to fix first.
	Reasons map[string]int `json:"reasons,omitempty"`
	// HandoffReuse counts the handoff-package calls of segment breaks by how they
	// were made (prefix, fallback:<reason>): whether the reuse of the segment
	// prefix held up (design 2026-10-27).
	HandoffReuse map[string]int `json:"handoff_reuse,omitempty"`
}

CacheBucketStat aggregates the calls of one cache bucket. InputTokens follows the report convention (cache excluded), so prompt = input + cache read + cache write; CacheHitRate = cache read / prompt.

type CacheBuckets

type CacheBuckets struct {
	Buckets        []CacheBucketStat `json:"cache_buckets"`
	LowSteady      []CacheLowHit     `json:"steady_low_hit,omitempty"`
	FailedAttempts int               `json:"failed_attempts,omitempty"`
}

CacheBuckets is the cache classification of one session or of several runs.

func AggregateCacheBuckets

func AggregateCacheBuckets(calls []CacheCall, lowHitLimit int) CacheBuckets

AggregateCacheBuckets pools classified calls into the per-bucket numbers plus the first lowHitLimit steady calls below SteadyLowHitBelow (0 lists none).

type CacheCall

type CacheCall struct {
	Bucket string `json:"bucket"`
	// FailedAttempt marks a provider attempt with no usable token usage. It is
	// retained for the aggregate's failed_attempts counter, never a bucket row.
	FailedAttempt bool `json:"-"`
	// Step is the 1-based ordinal of the main-loop model calls (the same step
	// number the trace analysis uses); a handoff side call keeps the step of the
	// call before it, since it is not a step of the loop.
	Step int `json:"step"`
	// Input includes the cache read/write of the call (the store's raw
	// convention); the bucket statistics report it without them.
	Input      int64 `json:"input_tokens"`
	CacheRead  int64 `json:"cache_read_tokens"`
	CacheWrite int64 `json:"cache_write_tokens"`
	// After names the prefix-changing events (fold, segment, truncate, tools)
	// recorded between the previous main-loop call and this one.
	After []string `json:"after,omitempty"`
	// Reason names why the call is in its bucket when the bucket is about a prefix
	// change: the request-prefix reason (system / tools / fold / segment / rewrite),
	// from attrs.prefix_resume_reason for a changed resume.
	Reason string `json:"reason,omitempty"`
	// PrefixTokens is the estimated size of the cacheable prefix of the previous
	// request, in tokens: what a provider cache could have served of this call.
	PrefixTokens int64 `json:"prefix_reused_tokens,omitempty"`
	// HandoffReuse is how a handoff-package call of a segment break was made
	// (attrs.handoff_reuse): prefix when it continued the segment's main-loop
	// request, fallback:<reason> when the old path asked instead.
	HandoffReuse string `json:"handoff_reuse,omitempty"`
}

CacheCall is one classified model call.

func ClassifyEvents

func ClassifyEvents(events []Event) []CacheCall

ClassifyEvents classifies the model calls of one session's events (oldest first, as ListEvents returns them).

type CacheLowHit

type CacheLowHit struct {
	Step     int      `json:"step"`
	Uncached int64    `json:"uncached_input_tokens"`
	Prompt   int64    `json:"prompt_tokens"`
	HitRate  float64  `json:"hit_rate"`
	Events   []string `json:"events,omitempty"` // events between the previous call and this one
}

CacheLowHit is one steady call whose hit rate stayed below SteadyLowHitBelow: where the next investigation of the hit rate starts.

type Entry

type Entry struct {
	SessionID string
	Seq       int64
	TurnID    string
	Type      string
	JSON      json.RawMessage
	CreatedAt time.Time
	// contains filtered or unexported fields
}

Entry is one record of a session's linear log. Seq is assigned by the store.

func (Entry) Stub

func (e Entry) Stub() bool

Stub reports whether the entry is a stub whose body still lives in the session file: such an entry holds only the fields a stub keeps (see buildToolBodyStub), not the bytes the row had before it moved.

type EntryFilter

type EntryFilter struct {
	SinceSeq int64 // only entries with seq > SinceSeq
	TurnID   string
	Types    []string
	Limit    int
	// NoHydrate returns the stubs as stored instead of reading the moved bodies
	// back from the session file. Use it when only the Content or the metadata of
	// the entries is read (an assistant stub keeps the whole Content, a tool stub
	// keeps the call id/name), and call Store.HydrateEntries for the entries that
	// do go on to a reader that needs the full body.
	NoHydrate bool
}

EntryFilter narrows ListEntries; zero values mean no restriction.

type EntryHit

type EntryHit struct {
	SessionID string
	Seq       int64
	Role      string
	Snippet   string
	CreatedAt time.Time
}

EntryHit is one matching entry, located by SessionID/Seq.

type EntryRef

type EntryRef struct {
	Seq       int64
	TurnID    string
	Type      string
	CallID    string
	CreatedAt time.Time
}

EntryRef is the minimal entry data a reader needs to link events to entries: the call id (tool call or result), the turn, the type and the time, without the entry body. The trace page joins the events of an incremental load against the whole session this way, without sending or parsing the bodies it already showed.

type EntrySearch

type EntrySearch struct {
	// Query is split on whitespace; every term must occur (AND). Terms are
	// literal text: FTS5 syntax characters have no special meaning.
	Query string
	// SessionIDs restrict the search to these sessions; empty means all.
	SessionIDs []string
	// CWDPrefix keeps only sessions whose cwd starts with it (plain string
	// prefix, case-sensitive); empty means no restriction.
	CWDPrefix string
	// WorkspaceDir restricts sessions to this directory and its descendants.
	// The comparison is on path-separator boundaries; an empty cwd is excluded.
	WorkspaceDir string
	// CurrentSessionID is always included with WorkspaceDir, even when that
	// session has no cwd. With no WorkspaceDir it restricts results to this ID.
	CurrentSessionID string
	// FoldCase applies SQLite's ASCII-only lower() folding to the workspace
	// comparison. Ledger enables it on Windows to match the approved semantics.
	FoldCase bool
	// Limit caps the hits: <=0 means 20, at most 100.
	Limit int
	// IncludeAgents searches sub-agent sessions too (they belong to their
	// parent session and are left out by default).
	IncludeAgents bool
	// Kinds restricts results to indexed entry roles. An empty slice means all
	// indexed roles; values must be user, assistant, tool, compaction or
	// handoff. tool only matches rows an older index left behind (tool results
	// are no longer indexed).
	Kinds []string
	// Since is an inclusive lower bound on entry creation time. Zero means no
	// lower bound.
	Since time.Time
	// Until is an exclusive upper bound on entry creation time. Zero means no
	// upper bound.
	Until time.Time
	// ExcludeSession drops one session's masked rows (the rows a conversation
	// rewind hid) from the hits; other sessions are untouched. The zero value
	// excludes nothing, which is what sugasdk and the CLI search with.
	ExcludeSession ExcludeSession
	// Cursor is a process-local snapshot position. Invalid or expired cursors
	// are ignored by SearchEntriesPage, which starts a fresh query.
	Cursor string
}

EntrySearch is a ledger full-text query.

type Event

type Event struct {
	ID               int64
	SessionID        string
	TurnID           string
	Kind             string
	Name             string
	Status           string
	StartedAt        time.Time
	DurationMs       int64
	TTFTMs           int64
	InputTokens      int64
	OutputTokens     int64
	CacheReadTokens  int64
	CacheWriteTokens int64
	Error            string
	Attrs            map[string]any
}

Event is one observability record (model call, tool call, turn ...).

type EventFilter

type EventFilter struct {
	SessionID string
	// WithAgents widens SessionID to its sub-agent sessions too.
	WithAgents bool
	TurnID     string
	Kinds      []string
	Since      time.Time
	Limit      int
	// ByID orders by ID instead of started_at, and AfterID (when > 0) keeps only
	// events with ID > AfterID: a stable cursor for paging.
	ByID    bool
	AfterID int64
}

EventFilter narrows ListEvents; zero values mean no restriction.

type ExcludeSession added in v0.54.0

type ExcludeSession struct {
	SessionID string
	Ranges    SeqRanges
}

ExcludeSession drops one session's masked rows from a search (EntrySearch. ExcludeSession). The zero value excludes nothing: sugasdk and the CLI search as before.

type ForkInput added in v0.54.0

type ForkInput struct {
	Session Session
	// Turns are stored with their own StartedAt/EndedAt/status; an empty
	// SessionID is filled with Session.ID.
	Turns []Turn
	// Entries must carry Seq 1..n in order and a CreatedAt.
	Entries []NewEntry
}

ForkInput is the complete payload of a forked session (session rewind design 0.2, R6). The caller maps everything beforehand: new turn ids, entries renumbered 1..n with their original CreatedAt, compaction and clear records pointing at the new seqs.

type GCReport

type GCReport struct {
	// Sessions last updated before the cutoff and not kept (newest first).
	Sessions []Session
	// Events counts the observability rows removed with those sessions plus
	// older rows whose session no longer exists.
	Events int64
	// SnapshotBytes is the on-disk size of snapshots below the sessions removed
	// by this report. It is populated by the CLI, which owns that file root.
	SnapshotBytes int64
	// Applied is false for a dry run.
	Applied bool
}

GCReport is what a garbage collection removes, or would remove on a dry run.

type GCRetentionClassReport

type GCRetentionClassReport struct {
	// Interactive names the class and Retention is the period applied to it.
	Interactive bool
	Retention   time.Duration
	// Sessions are the sessions of the class this pass removes (or would).
	Sessions []Session
	// Entries counts all stored entries of those sessions.
	Entries int64
	// EstimatedBytes approximates the stored bytes they hold: the entry JSON
	// bodies plus the session meta. It is an estimate - snapshots, the events
	// and the free pages of the file are not counted, and only a VACUUM
	// returns space to the disk.
	EstimatedBytes int64
}

GCRetentionClassReport is what one retention class of a retention pass removes, or would remove on a dry run.

type GCRetentionPolicy

type GCRetentionPolicy struct {
	// Interactive applies to chat sessions and to sessions created before
	// meta.origin existed; NonInteractive to run, ACP and sub-agent sessions.
	Interactive    time.Duration
	NonInteractive time.Duration
}

GCRetentionPolicy is the per-class session retention of `suga data gc --retention`. A period of zero or less turns its class off: those sessions are kept.

type GCRetentionReport

type GCRetentionReport struct {
	Interactive    GCRetentionClassReport
	NonInteractive GCRetentionClassReport
	// Applied is false for a dry run.
	Applied bool
}

GCRetentionReport is the result of a retention pass, one entry per class.

func (GCRetentionReport) Classes

Classes lists both classes, interactive first.

func (GCRetentionReport) Sessions

func (r GCRetentionReport) Sessions() []Session

Sessions lists every session the pass removes, interactive first.

type MemoryHit

type MemoryHit struct {
	ID      string
	Snippet string
	Updated time.Time
}

MemoryHit is a ranked hit from memory_fts. The adapter fills the entry's title and kind from the same enumeration used to build the source rows.

type MemoryMeta

type MemoryMeta struct {
	Backend, Scope, EntryID string
	UUID                    string
	SessionID, TurnID       string
	Source                  string
	Tainted                 bool
	DeletedAt               time.Time
	Fingerprint             string
	CreatedAt, UpdatedAt    time.Time
}

MemoryMeta is one memory_meta row (stats, export and tests).

type MemoryRef added in v0.52.0

type MemoryRef struct {
	Backend, Scope, EntryID, UUID string
}

MemoryRef locates a live memory entry by its stable UUID.

type MemorySource

type MemorySource struct {
	ID      string
	Text    string
	Updated time.Time
}

MemorySource is one files-backed entry projected into the derived FTS index. Text is deliberately supplied by the caller: Markdown remains the source of truth and the store only owns the rebuildable SQLite projection.

type ModelStat

type ModelStat struct {
	Provider       string  `json:"provider"`
	Model          string  `json:"model"`
	Calls          int     `json:"calls"`
	EstimatedCalls int     `json:"estimated_calls,omitempty"`
	Errors         int     `json:"errors"`
	ErrorRate      float64 `json:"error_rate"`
	P50Ms          int64   `json:"p50_ms"`
	P95Ms          int64   `json:"p95_ms"`
	P50TTFTMs      int64   `json:"p50_ttft_ms,omitempty"`
	InputTokens    int64   `json:"input_tokens"`
	OutputTokens   int64   `json:"output_tokens"`
	CacheRead      int64   `json:"cache_read_tokens"`
	CacheWrite     int64   `json:"cache_write_tokens"`
	CacheHitRate   float64 `json:"cache_hit_rate"`
	CostUSD        float64 `json:"cost_usd"`
}

ModelStat aggregates kind=model events of one provider/model pair. InputTokens follows the REPORTING convention (cache excluded, see personal.ReportUsage): stored input minus cache read/write, floored at 0 per event. CacheHitRate = cache_read / (input + cache_read + cache_write).

type NamedStat

type NamedStat struct {
	Name  string `json:"name"`
	Rows  int64  `json:"rows,omitempty"`
	Bytes int64  `json:"bytes"`
}

NamedStat is one row of a breakdown (an entry type, an event kind, a JSON field, a tool name).

type NewEntry

type NewEntry struct {
	TurnID string
	Type   string
	JSON   json.RawMessage
	// Seq and CreatedAt are read only by CreateForkedSession, where the caller
	// maps them beforehand; AppendEntries assigns both itself and ignores them.
	Seq       int64
	CreatedAt time.Time
}

NewEntry is the input form of Entry for AppendEntries.

type Option

type Option func(*Store)

Option adjusts what a Store knows besides its database file.

func WithSessionsDir

func WithSessionsDir(dir string) Option

WithSessionsDir sets the sessions root that holds the tool body files (default: <db dir>/../sessions).

func WithToolBodyInlineBytes

func WithToolBodyInlineBytes(n int64) Option

WithToolBodyInlineBytes sets the tool body threshold (default 1024, 0 keeps every body inline).

type Report

type Report struct {
	Models      []ModelStat `json:"models"`
	Tools       []ToolStat  `json:"tools"`
	Compactions int         `json:"compactions"`
	ToolSearch  int         `json:"tool_searches"`
	// FailedAttempts counts provider attempts omitted from cache buckets because
	// they failed or reported no token usage.
	FailedAttempts int `json:"failed_attempts,omitempty"`
	// CacheBuckets splits the model calls by cache bucket (see CacheBucket*).
	// BuildReport leaves it nil - its SQL pass is bucket-blind - and the stats
	// command fills it from BuildCacheBuckets, so a caller that wants only the
	// model and tool rows pays nothing for it.
	CacheBuckets []CacheBucketStat `json:"cache_buckets,omitempty"`
}

Report is the result of `suga inspect stats`.

func AggregateEvents

func AggregateEvents(events []Event) Report

AggregateEvents is the pure aggregation behind BuildReport; the SQL report must keep producing the same result (TestBuildReportMatchesAggregateEvents).

type RewindRecord added in v0.54.0

type RewindRecord struct {
	// Seq is the record's own seq; the masked interval is (CutSeq, Seq).
	Seq int64
	// CutSeq is the seq of the last entry kept before the rewound turn.
	CutSeq     int64
	TargetTurn string
	Scope      string
}

RewindRecord is one stored EntryRewind record.

type SearchResult

type SearchResult struct {
	Hits       []EntryHit
	NextCursor string
	Notice     string
}

SearchResult contains one page and the optional continuation metadata. Notice is informational: a stale cursor or a snapshot truncated at 500 hits never turns a valid search into an error.

type SeqRange added in v0.54.0

type SeqRange struct{ Lo, Hi int64 }

SeqRange is the open interval (Lo, Hi): the seqs Lo < seq < Hi are masked, Lo and Hi themselves are not.

type SeqRanges added in v0.54.0

type SeqRanges []SeqRange

SeqRanges is a sorted list of disjoint masked intervals; build it with NewSeqRanges. The zero value masks nothing.

func NewSeqRanges added in v0.54.0

func NewSeqRanges(rs ...SeqRange) SeqRanges

NewSeqRanges sorts rs, drops the intervals that mask no integer (Hi-Lo <= 1) and merges overlapping ones. (1,5) and (4,9) merge into (1,9); (1,5) and (5,9) stay apart because seq 5 is masked by neither.

func RangesOf added in v0.54.0

func RangesOf(recs []RewindRecord) SeqRanges

RangesOf is the masked intervals of a session's rewind records.

func (SeqRanges) Hidden added in v0.54.0

func (r SeqRanges) Hidden(seq int64) bool

Hidden reports whether seq lies inside a masked interval (binary search).

type Session

type Session struct {
	ID         string
	Title      string
	Cwd        string
	Status     string
	LastTurnID string
	CreatedAt  time.Time
	UpdatedAt  time.Time
	Meta       map[string]any
}

Session is one conversation. Meta holds free-form keys (rules hash, append prompt, effective model, loaded deferred tools, usage ...).

type SizeStat

type SizeStat struct {
	Rows  int64 `json:"rows,omitempty"`
	Files int64 `json:"files,omitempty"`
	Bytes int64 `json:"bytes"`
}

SizeStat is a row or file count with the bytes it occupies. Rows counts ledger records, Files counts files on disk; a section fills the one that applies.

type Store

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

Store wraps the shared *sql.DB of the core store.

func Open

func Open(path string, opts ...Option) (*Store, error)

Open opens (creating if needed) the store at path and applies pending migrations. Repeated opens are idempotent.

func OpenReadOnly

func OpenReadOnly(path string, opts ...Option) (*Store, error)

OpenReadOnly opens an existing store for reading only: it never creates the file, never migrates and never writes. A missing file or a database without the migration ledger (an empty or foreign file) is reported as an error, so a read-only page cannot touch a session store it merely is asked to show.

func (*Store) AgentStorage

func (s *Store) AgentStorage() *AgentStorage

AgentStorage returns the agentcore storage adapter for this store.

func (*Store) AppendEntries

func (s *Store) AppendEntries(ctx context.Context, sessionID string, in ...NewEntry) ([]Entry, error)

AppendEntries appends a batch to the session log in one transaction and returns the stored entries with their assigned seq (contiguous, per session).

A tool or assistant entry whose body is larger than store.body_inline_bytes moves into the session body file (tools.jsonl or bodies.jsonl) inside this transaction (design 0.3): the row, the record and the swap to the stub commit together, and a failure of the file write rolls the transaction back after truncating the file to the length it had. The returned entries keep the full body. An assistant entry moves only when its stub saves more than the threshold (design 2026-10-20, revision 8): a big Content without large Reasoning/Metadata stays inline, since the stub has to keep the Content anyway.

func (*Store) AppendEvent

func (s *Store) AppendEvent(ctx context.Context, e Event) (Event, error)

AppendEvent inserts one event and returns it with its assigned ID.

func (*Store) BackfillMemoryUUIDs added in v0.52.0

func (s *Store) BackfillMemoryUUIDs(ctx context.Context) error

BackfillMemoryUUIDs fills UUIDs on rows from databases created before the UUID migration. It runs in one transaction so opening a large store is safe.

func (*Store) BuildCacheBuckets

func (s *Store) BuildCacheBuckets(ctx context.Context, f EventFilter, lowHitLimit int) (CacheBuckets, error)

BuildCacheBuckets classifies the model calls matching f and aggregates them per cache bucket. The buckets are per session: the cold bucket is a session's own first call, so the query is grouped by session id and the rows of one session reach the classifier in time order. lowHitLimit caps the listed steady low-hit calls (0 lists none).

func (*Store) BuildReport

func (s *Store) BuildReport(ctx context.Context, f EventFilter) (Report, error)

BuildReport queries events matching f (session/since) and aggregates them in SQL: GROUP BY/COUNT/SUM for the totals and one windowed pass per group kind for the nearest-rank percentiles. The result equals AggregateEvents over the same events (TestBuildReportMatchesAggregateEvents), but a report over a large ledger no longer pulls every event through Go and JSON-decodes its attrs.

func (*Store) Close

func (s *Store) Close() error

Close releases the database handle. A shared handle closes with its last store; closing twice is harmless.

func (*Store) CollectGarbage

func (s *Store) CollectGarbage(ctx context.Context, cutoff time.Time, keep map[string]bool, apply bool) (GCReport, error)

CollectGarbage removes sessions not updated since cutoff (and the sub-agent sessions they started), with their turns and entries (ON DELETE CASCADE) and their events, plus events older than cutoff that belong to no session. keep lists session IDs never removed (sessions with a live process). Without apply nothing is written.

The removal runs in batches of gcBatchSessions sessions, each in its own short write transaction, so a cleanup of hundreds of sessions can be interrupted with Ctrl-C and keeps what it already committed. It does NOT VACUUM: returning the freed space to the disk is the explicit `suga data vacuum`, which reports separately from the deleted rows (design 0.3, P3).

func (*Store) CollectGarbageByRetention

func (s *Store) CollectGarbageByRetention(ctx context.Context, now time.Time, policy GCRetentionPolicy, keep map[string]bool, apply bool) (GCRetentionReport, error)

CollectGarbageByRetention removes the sessions whose class retention period has passed. keep lists the sessions never removed (a live process or a held lock). Without apply nothing is written.

func (*Store) CountEntriesByType

func (s *Store) CountEntriesByType(ctx context.Context, sessionID, typ string) (int, error)

CountEntriesByType counts a session's entries of one type. The query is a range scan of that session's primary-key rows with the type filter, never a walk of the whole entries table.

func (*Store) CountEntriesByTypeSkipping added in v0.54.0

func (s *Store) CountEntriesByTypeSkipping(ctx context.Context, sessionID, typ string, skip SeqRanges) (int, error)

CountEntriesByTypeSkipping is CountEntriesByType over the entries outside skip. It is CountEntriesByType minus the masked rows, in one query that keeps the plain count's plan (idx_entries_type: the rows of one type are few); a per-segment primary-key range count read every row of the session instead (3ms against 30us on 20k entries). An empty skip is CountEntriesByType.

func (*Store) CountTurns

func (s *Store) CountTurns(ctx context.Context, sessionID string) (int, error)

CountTurns counts a session's turns (idx_turns_session, no table scan). It reads the index only: a turn's state_json is never loaded.

func (*Store) CountTurnsSkipping added in v0.54.0

func (s *Store) CountTurnsSkipping(ctx context.Context, sessionID string, skip SeqRanges) (int, error)

CountTurnsSkipping counts a session's turns outside the masked intervals skip. A turn is masked when it has entries and all of them are masked; a turn with no entry at all counts as before. It is CountTurns when skip is empty.

func (*Store) CreateForkedSession added in v0.54.0

func (s *Store) CreateForkedSession(ctx context.Context, in ForkInput) error

CreateForkedSession writes the session, its turns and its entries in one write transaction. Entries go through the same in-transaction path as AppendEntries (insertEntryTx), so a fork row is indexed in entries_fts and a big tool or assistant body moves to the new session's body file exactly as it would in a normal append, with the original created_at kept. Any failure rolls the transaction back and drops the body file this call created, so a failed fork leaves neither rows nor files behind. The seq check (1..n, contiguous) runs before the transaction opens.

func (*Store) CreateSession

func (s *Store) CreateSession(ctx context.Context, in Session) error

CreateSession inserts a new session. Empty Status defaults to open and zero timestamps to now.

func (*Store) CreateTurn

func (s *Store) CreateTurn(ctx context.Context, in Turn) error

CreateTurn inserts a turn. Status defaults to running, StartedAt to now.

func (*Store) DB

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

DB exposes the handle for read-only queries by sibling packages.

func (*Store) DeleteSession

func (s *Store) DeleteSession(ctx context.Context, id string) error

DeleteSession removes a session with its turns and entries (ON DELETE CASCADE). Events are kept: they have no foreign key and record spent tokens.

func (*Store) DeleteSessionFiles

func (s *Store) DeleteSessionFiles(sessionIDs ...string) error

DeleteSessionFiles removes the files of sessions the ledger no longer has (called by the catalogues that delete a session outside `data gc`, which removes the whole session directory itself).

func (*Store) EnsureMemoryUUID added in v0.52.0

func (s *Store) EnsureMemoryUUID(ctx context.Context, backend string, sc memory.Scope, id string) (string, error)

EnsureMemoryUUID creates the metadata for an old live entry that predates UUIDs. If an ID currently points at a tombstone, that row is archived first.

func (*Store) EntriesAround added in v0.52.0

func (s *Store) EntriesAround(ctx context.Context, sessionID string, seq int64, window int) ([]Entry, error)

EntriesAround returns the target entry and up to window entries on either side, ordered by the stable session sequence. Entry rows are append-only: AppendEntries assigns the next sequence, while session deletion is the only production path that removes entries (through the sessions foreign-key cascade); no path renumbers an existing sequence.

func (*Store) EntriesFromSkipping added in v0.54.0

func (s *Store) EntriesFromSkipping(ctx context.Context, sessionID string, types []string, fromSeq int64, skip SeqRanges, limit int) ([]Entry, error)

EntriesFromSkipping returns up to limit entries of the given types with seq >= fromSeq outside skip, oldest first: the window read of recall. Empty types return nothing (as RecentEntries); the caller asks for one row more than it shows when it needs the seq the next window continues from.

func (*Store) FTSShrinkPending

func (s *Store) FTSShrinkPending(ctx context.Context) (bool, error)

FTSShrinkPending reports whether the ledger still holds tool rows in the index: the search notice tells the model that a search covers user and AI messages only once those rows are gone. It is asked once per store handle (see noteShrinkPending), so the row scan is not run on every search.

func (*Store) GetSession

func (s *Store) GetSession(ctx context.Context, id string) (Session, error)

GetSession returns the session or ErrSessionNotFound.

func (*Store) GetTurn

func (s *Store) GetTurn(ctx context.Context, id string) (Turn, error)

GetTurn returns the turn or ErrTurnNotFound.

func (*Store) HasSearchableEntries

func (s *Store) HasSearchableEntries(ctx context.Context, q EntrySearch) (bool, error)

HasSearchableEntries reports whether the scope of q holds any searchable entry at all (an indexed type with text): when it does not, no wording can match anything here, and the caller says so instead of letting the model try one query after another (suag-hpu7). Query, Limit, Cursor, Since and Until are ignored; SessionIDs, WorkspaceDir, CurrentSessionID, FoldCase, Kinds and IncludeAgents pick the scope exactly as SearchEntriesPage does. The retrieval tools' own transcripts count as entries here (only excluding them from a match is cheap to skip), so a ledger holding nothing else reports true.

func (*Store) HydrateEntries

func (s *Store) HydrateEntries(ctx context.Context, sessionID string, entries []Entry) error

HydrateEntries replaces the stubs among entries with the bodies their records hold; entries that are inline stay as they are. Callers that list entries without their bodies (EntryFilter.NoHydrate) use it to fetch exactly the ones they send on. A session without a stub in entries costs no file access.

func (*Store) IsTombstoned

func (s *Store) IsTombstoned(ctx context.Context, backend string, sc memory.Scope, fingerprint string) (bool, error)

IsTombstoned implements memory.ProvenanceStore.

func (*Store) LastEntryAt

func (s *Store) LastEntryAt(ctx context.Context, sessionID string) (time.Time, error)

LastEntryAt is the time of a session's newest entry (the zero time when the session has none). The primary key makes this a single index read plus the row it points at.

func (*Store) LastEntrySeq added in v0.52.0

func (s *Store) LastEntrySeq(ctx context.Context, sessionID string) (int64, error)

LastEntrySeq returns the highest entries seq of the session, 0 when it has none. A segment record that keeps nothing starts after it (--clear-ctx).

func (*Store) LatestEntry

func (s *Store) LatestEntry(ctx context.Context, sessionID, typ string) (*Entry, error)

LatestEntry returns the highest-seq entry of the given type, or (nil, nil) when the session has none.

func (*Store) LatestEntrySkipping added in v0.54.0

func (s *Store) LatestEntrySkipping(ctx context.Context, sessionID, typ string, skip SeqRanges) (*Entry, error)

LatestEntrySkipping is LatestEntry over the entries outside skip, or (nil, nil) when none is visible.

func (*Store) ListEntries

func (s *Store) ListEntries(ctx context.Context, sessionID string, f EntryFilter) ([]Entry, error)

ListEntries returns entries ordered by seq, narrowed by f.

func (*Store) ListEntryRefs

func (s *Store) ListEntryRefs(ctx context.Context, sessionID string) ([]EntryRef, error)

ListEntryRefs returns the link fields of every entry of a session, oldest first, with the bodies left in the store (see EntryRef).

func (*Store) ListEvents

func (s *Store) ListEvents(ctx context.Context, f EventFilter) ([]Event, error)

ListEvents returns events oldest first (started_at, id), narrowed by f.

func (*Store) ListSessions

func (s *Store) ListSessions(ctx context.Context) ([]Session, error)

ListSessions returns all sessions, most recently updated first.

func (*Store) ListTurns

func (s *Store) ListTurns(ctx context.Context, sessionID string, statuses ...string) ([]Turn, error)

ListTurns returns a session's turns oldest first, optionally filtered by status.

func (*Store) MemoryMetaRows

func (s *Store) MemoryMetaRows(ctx context.Context, backend string, sc memory.Scope) ([]MemoryMeta, error)

MemoryMetaRows lists the rows of one backend and scope ordered by entry id.

func (*Store) MemoryRefByUUID added in v0.52.0

func (s *Store) MemoryRefByUUID(ctx context.Context, uuid string) (MemoryRef, error)

MemoryRefByUUID resolves only live rows; tombstones remain auditable through MemoryMetaRows but cannot be used to mutate a deleted memory entry.

func (*Store) MoveAssistantBodies

func (s *Store) MoveAssistantBodies(ctx context.Context, opts ToolBodyMaintOptions) (ToolBodyMaintReport, error)

MoveAssistantBodies moves historical assistant bodies with an independent checkpoint.

func (*Store) MoveToolBodies

func (s *Store) MoveToolBodies(ctx context.Context, opts ToolBodyMaintOptions) (ToolBodyMaintReport, error)

MoveToolBodies moves the historical tool bodies into the session files, at most Batch rows (or toolBodyBatchBytes) per write transaction, resumable through a (session_id, seq) checkpoint. Rows that are stubs already are skipped, so a rerun continues and an interrupted batch is repeated safely.

func (*Store) PatchSessionMeta

func (s *Store) PatchSessionMeta(ctx context.Context, id string, patch map[string]any) error

PatchSessionMeta merges patch into meta_json atomically (a nil value deletes the key), so concurrent processes cannot roll back each other's keys.

func (*Store) PatchSessionMetaIfAbsent

func (s *Store) PatchSessionMetaIfAbsent(ctx context.Context, id, guard string, patch map[string]any) (bool, error)

PatchSessionMetaIfAbsent applies patch only when meta has no guard key yet, in the same transaction as the check, so concurrent writers cannot both apply it (write-once keys such as tainted_at). It reports whether the patch was applied.

func (*Store) Path

func (s *Store) Path() string

Path returns the absolute database file path.

func (*Store) RecentEntries

func (s *Store) RecentEntries(ctx context.Context, sessionID string, types []string, limit int) ([]Entry, error)

RecentEntries returns the newest entries of the given types, newest first, at most limit of them (nil when the session has none). It walks the (session_id, seq) primary key backwards and stops after limit rows, so a session with a very long log still answers from a few index reads.

func (*Store) RecentEntriesSkipping added in v0.54.0

func (s *Store) RecentEntriesSkipping(ctx context.Context, sessionID string, types []string, skip SeqRanges, limit int) ([]Entry, error)

RecentEntriesSkipping is RecentEntries over the entries outside the masked intervals skip (newest first, at most limit). It walks the visible segments from the newest, one (session_id, seq) primary-key range query each, and stops when limit rows are found: a large masked interval at the tail costs one empty range read, not a walk over its rows. An empty skip is one query, the same as RecentEntries.

func (*Store) Record

func (s *Store) Record(ctx context.Context, backend string, sc memory.Scope, e memory.Entry, fingerprint string) error

Record implements memory.ProvenanceStore: it upserts the provenance of an added or replaced entry and clears any tombstone of the same id.

Ids are reused (an add may get the id of an entry removed earlier), but the primary key holds one row per id. So before the live row replaces a tombstone, the tombstone is archived under "<id>@<fingerprint prefix>" in the same transaction; IsTombstoned keeps matching it by fingerprint, and its UUID remains available for audit and migration checks.

func (*Store) RemoveToolBodyFiles

func (s *Store) RemoveToolBodyFiles(ctx context.Context) (removed int, err error)

RemoveToolBodyFiles deletes the session files of sessions that keep no stub, each confirmed under the write lock so a writer that moved a body out in the meantime is not robbed of its file. It is the --undo --remove-files step.

func (*Store) ResetToolBodyState

func (s *Store) ResetToolBodyState(ctx context.Context) error

ResetToolBodyState drops both checkpoints (--abort): the next pass starts at the first row again.

func (*Store) RewindRecords added in v0.54.0

func (s *Store) RewindRecords(ctx context.Context, sid string) ([]RewindRecord, error)

func (*Store) SearchEntries

func (s *Store) SearchEntries(ctx context.Context, q EntrySearch) ([]EntryHit, error)

SearchEntries preserves the pre-cursor API for callers that only need hits. The page-aware API is SearchEntriesPage; it owns snapshot creation and continuation metadata.

func (*Store) SearchEntriesPage

func (s *Store) SearchEntriesPage(ctx context.Context, q EntrySearch) (SearchResult, error)

SearchEntriesPage returns one bounded page from a stable process-local snapshot. The SQL runs only when Cursor is empty or its snapshot is stale; valid continuation cursors slice the stored hits and preserve their original snippets and ordering.

func (*Store) SearchMemoryIndex

func (s *Store) SearchMemoryIndex(ctx context.Context, scope, q string, limit int) ([]MemoryHit, error)

SearchMemoryIndex searches one scope with the same trigram/short-term split as session search. Long terms use FTS5 bm25 ranking; one- and two-rune terms remain LIKE filters so CJK and short identifiers are still searchable.

func (*Store) SessionCwds

func (s *Store) SessionCwds(ctx context.Context) (map[string]string, error)

SessionCwds returns id -> cwd of every session with a recorded cwd. It reads only those two columns (meta_json can be large), for callers that match paths themselves (e.g. with path-separator boundaries).

func (*Store) SetToolBodyMove

func (s *Store) SetToolBodyMove(ctx context.Context, enabled bool) error

SetToolBodyMove writes the persistent switch: false keeps every new tool body inline until a later `--move` turns it on again.

func (*Store) Snapshot

func (s *Store) Snapshot(ctx context.Context, destination string) error

Snapshot writes a transactionally consistent SQLite snapshot to destination. VACUUM INTO is deliberately explicit: it never copies a live WAL or SHM file.

func (*Store) SumUsage

func (s *Store) SumUsage(ctx context.Context, sessionID string) (Usage, error)

SumUsage totals tokens over kind=model events only; turn/tool events carry no per-call usage of their own, so nothing is counted twice. Cost is the sum of the optional attrs.cost_usd of those events.

func (*Store) SumUsageTree

func (s *Store) SumUsageTree(ctx context.Context, sessionID string) (Usage, error)

SumUsageTree is SumUsage over the session and its sub-agent sessions (meta parent_session_id = sessionID): what the session spent in all, as its cumulative usage reports it.

func (*Store) SyncMemoryIndex

func (s *Store) SyncMemoryIndex(ctx context.Context, scope string, sources []MemorySource) (added, removed int, err error)

SyncMemoryIndex incrementally makes memory_fts match sources for scope. A single transaction makes a search see either the old projection or the new one; changed rows are deleted before insertion because FTS5 has no ordinary UPDATE semantics for its UNINDEXED metadata columns.

func (*Store) Tombstone

func (s *Store) Tombstone(ctx context.Context, backend string, sc memory.Scope, id, fingerprint string) error

Tombstone implements memory.ProvenanceStore: it marks the entry removed and stores the fingerprint of the removed content. An empty fingerprint keeps the one recorded with the entry. Entries without a provenance row get a UUID now, so a later ID reuse cannot erase this tombstone's identity.

func (*Store) ToolBodyCheck

func (s *Store) ToolBodyCheck(ctx context.Context) (ToolBodyCheckReport, error)

ToolBodyCheck verifies every stub and reports what does not line up. It only reads: a missing body or an orphan record is left for the operator (restore from a backup, or --undo when the file is still complete).

func (*Store) ToolBodyStatus

func (s *Store) ToolBodyStatus(ctx context.Context) (ToolBodyStatus, error)

ToolBodyStatus reports what is left to move, what moved and how large the session files are.

func (*Store) UndoToolBodies

func (s *Store) UndoToolBodies(ctx context.Context, opts ToolBodyMaintOptions) (ToolBodyMaintReport, error)

UndoToolBodies restores every moved body into the ledger and disables new moves.

func (*Store) UpdateEventEntrySeq

func (s *Store) UpdateEventEntrySeq(ctx context.Context, id, seq int64) error

UpdateEventEntrySeq fills the sequence of a pending injected entry after the next turn stores it. The event is written when undo completes, while the entry itself is deliberately deferred until the user starts another turn.

func (*Store) UpdateSession

func (s *Store) UpdateSession(ctx context.Context, in Session) error

UpdateSession overwrites title, cwd, status, last_turn_id and meta of an existing session. UpdatedAt defaults to now when zero.

func (*Store) UpdateSessionFields

func (s *Store) UpdateSessionFields(ctx context.Context, in Session) error

UpdateSessionFields sets title, cwd, status, last_turn_id and updated_at of an existing session and leaves its meta alone. Meta is patched by key (PatchSessionMeta, PatchSessionMetaIfAbsent) by several writers, e.g. a background task marking the session tainted while a turn runs; writing back a meta read earlier (UpdateSession) would drop what they added meanwhile. UpdatedAt defaults to now when zero.

func (*Store) UpdateTurn

func (s *Store) UpdateTurn(ctx context.Context, t Turn) error

UpdateTurn writes status, stop_reason and ended_at (state_json is owned by UpsertTurnState and left untouched).

func (*Store) UpsertTurnState

func (s *Store) UpsertTurnState(ctx context.Context, turnID string, stateJSON []byte) error

UpsertTurnState stores the agentcore RunState snapshot of an existing turn.

func (*Store) Usage

func (s *Store) Usage(ctx context.Context, opts UsageOptions) (UsageReport, error)

Usage builds the storage report. It reads through s, so it must be a read-only store; no statement writes.

func (*Store) Vacuum

func (s *Store) Vacuum(ctx context.Context) (VacuumResult, error)

Vacuum rewrites the database file so that the space freed by deletions and the FTS shrink returns to the disk, then truncates the WAL. It needs roughly as much free space as the file is large (SQLite writes a new file and swaps it in), so the caller checks that first. The store must not be used from another process while it runs: VACUUM rewrites every page.

type ToolBodyCheckReport

type ToolBodyCheckReport struct {
	// Checked is the number of stub rows verified, Missing those whose body could
	// not be read back (the ledger points at nothing valid).
	Checked int64
	Missing int64
	// OrphanRecords are records no stub points at (a crash before the commit of a
	// moved body leaves one), OrphanBytes their size.
	OrphanRecords int64
	OrphanBytes   int64
	// Problems lists the first few failures, for the operator to see.
	Problems []string
}

ToolBodyCheckReport is what --check found. It only reports: cleaning an orphan record would rewrite the file and move every offset after it, which has to happen under the write lock with the stubs, and is left out of this version.

func (ToolBodyCheckReport) OK

func (r ToolBodyCheckReport) OK() bool

OK reports whether the ledger and its files agree.

type ToolBodyMaintOptions

type ToolBodyMaintOptions struct {
	Batch   int
	OnBatch func(ToolBodyMaintProgress)
}

ToolBodyMaintOptions configures one pass. The zero value is the CLI default.

type ToolBodyMaintProgress

type ToolBodyMaintProgress struct {
	// SessionID and Seq are the cursor after the batch.
	SessionID string
	Seq       int64
	// Rows and Bytes are the totals of the pass so far.
	Rows  int64
	Bytes int64
}

ToolBodyMaintProgress is one finished batch.

type ToolBodyMaintReport

type ToolBodyMaintReport struct {
	Rows    int64
	Bytes   int64
	Batches int
	// CursorSession and CursorSeq are the checkpoint the pass reached; Complete is
	// false only when the caller stopped it with ctx.
	CursorSession string
	CursorSeq     int64
	Complete      bool
}

ToolBodyMaintReport describes what one pass did.

type ToolBodyStatus

type ToolBodyStatus struct {
	// InlineBytes is the threshold in force; MoveEnabled is the persistent switch
	// (false after --undo).
	InlineBytes int64
	MoveEnabled bool
	// PendingRows and PendingBytes are the tool rows that would still move;
	// AssistantPending* the same for assistant entries (the migration of revision
	// 3, an independent pass). AssistantSkippedRows (and its bytes) are the SQL
	// candidates the assistant pass leaves alone because moving them out saves no
	// more than the threshold: counted apart so --status does not ask for a --move
	// run that cannot do anything.
	PendingRows          int64
	PendingBytes         int64
	AssistantPendingRows int64
	AssistantPending     int64
	AssistantSkippedRows int64
	AssistantSkipped     int64
	// MovedRows are the rows whose body lives in a file, FileBytes and Files what
	// the session files hold (both file names).
	MovedRows          int64
	AssistantMovedRows int64
	FileBytes          int64
	Files              int
	// BodyFileNameEnabled is the file name switch (set by v0.40's --rename-files);
	// LegacyNameFiles counts the sessions still holding a tools.jsonl file. Both
	// are read-only information: this version writes whichever name the switch
	// names, so a renamed ledger keeps working.
	BodyFileNameEnabled bool
	LegacyNameFiles     int
	// The checkpoints of both passes.
	MoveStarted, MoveComplete bool
	MoveSession               string
	MoveSeq, MoveRows         int64
	AssistantMoveStarted      bool
	AssistantMoveComplete     bool
	AssistantMoveSession      string
	AssistantMoveSeq          int64
	AssistantMoveRows         int64
	UndoStarted, UndoComplete bool
	UndoRows                  int64
}

ToolBodyStatus is what --status reports.

type ToolStat

type ToolStat struct {
	Name      string  `json:"name"`
	Calls     int     `json:"calls"`
	Errors    int     `json:"errors"`
	ErrorRate float64 `json:"error_rate"`
	Denials   int     `json:"denials"`
	P50Ms     int64   `json:"p50_ms"`
	P95Ms     int64   `json:"p95_ms"`
	// RawBytes / InlineBytes sum the tool output produced and the part kept in
	// the session (event attrs raw_bytes / inline_bytes); Spilled counts calls
	// whose full output was saved to the session directory.
	RawBytes    int64 `json:"raw_bytes"`
	InlineBytes int64 `json:"inline_bytes"`
	Spilled     int   `json:"spilled"`
}

ToolStat aggregates tool events by tool name. Calls counts executed tool events; denial events (which replace the tool event when approval refuses a call) are counted in Denials only.

type Turn

type Turn struct {
	ID         string
	SessionID  string
	Status     string
	StopReason string
	StateJSON  []byte // agentcore RunState snapshot; empty until SaveRun
	StartedAt  time.Time
	EndedAt    time.Time
}

Turn is one user request and its agentcore run (run_id == turn id).

type Usage

type Usage struct {
	Calls            int64
	InputTokens      int64
	OutputTokens     int64
	CacheReadTokens  int64
	CacheWriteTokens int64
	CostUSD          float64
}

Usage is the token total returned by SumUsage.

type UsageAssistant

type UsageAssistant struct {
	Rows         int64       `json:"rows"`
	Bytes        int64       `json:"bytes"`
	Fields       []NamedStat `json:"fields"`
	MetadataKeys []NamedStat `json:"metadata_keys"`
	Tools        []NamedStat `json:"tool_arguments"`
}

UsageAssistant splits the assistant entries, which carry the bulk of the ledger: their JSON fields, the metadata keys and the tool call arguments. The numbers describe what is still inside the ledger; a row whose body moved to a session file only counts the stub (see UsageEntries.MovedAssistant).

type UsageEntries

type UsageEntries struct {
	Rows      int64            `json:"rows"`
	Bytes     int64            `json:"bytes"`
	Types     []NamedStat      `json:"types"`
	Assistant UsageAssistant   `json:"assistant"`
	Tool      UsageToolEntries `json:"tool"`
	// MovedAssistant are the assistant rows whose body lives in a session file
	// (entries.body_ref set, only a stub in the ledger). Their Reasoning,
	// Metadata and call arguments are in the file, so the Values above no longer
	// count them.
	MovedAssistant SizeStat `json:"moved_assistant"`
	Suggestion     string   `json:"suggestion,omitempty"`
}

UsageEntries is the entries table by type and by large JSON field.

type UsageEvents

type UsageEvents struct {
	Rows       int64       `json:"rows"`
	Bytes      int64       `json:"bytes"`
	Kinds      []NamedStat `json:"kinds"`
	Suggestion string      `json:"suggestion,omitempty"`
}

UsageEvents is the events table by kind. Bytes counts attrs_json and error, the two free-form columns.

type UsageFTS

type UsageFTS struct {
	Rows         int64       `json:"rows"`
	Roles        []NamedStat `json:"roles"`
	DataBytes    int64       `json:"data_bytes"`
	ContentBytes int64       `json:"content_bytes"`
	Bytes        int64       `json:"bytes"`
	Suggestion   string      `json:"suggestion,omitempty"`
}

UsageFTS is the entries_fts index: its rows (one per indexed entry) and the bytes of its shadow tables.

type UsageFile

type UsageFile struct {
	Path      string `json:"path"`
	Bytes     int64  `json:"bytes"`
	PageSize  int64  `json:"page_size"`
	Pages     int64  `json:"pages"`
	FreePages int64  `json:"free_pages"`
	FreeBytes int64  `json:"free_bytes"`
	WALBytes  int64  `json:"wal_bytes"`
	// Suggestion names the command that acts on this section ("" if none).
	Suggestion string `json:"suggestion,omitempty"`
}

UsageFile is the database file itself.

type UsageOptions

type UsageOptions struct {
	Top int
	// Translator renders human-facing maintenance suggestions. A nil translator
	// uses the Chinese fallback for callers predating language injection.
	Translator i18n.Translator
}

UsageOptions narrows the usage report. Top bounds every "N largest" list.

type UsageReport

type UsageReport struct {
	File     UsageFile     `json:"file"`
	Entries  UsageEntries  `json:"entries"`
	Events   UsageEvents   `json:"events"`
	FTS      UsageFTS      `json:"fts"`
	Sessions UsageSessions `json:"sessions"`
	// Tables holds the dbstat page usage (largest first) and DBStat says
	// whether this build of SQLite has the virtual table.
	Tables []UsageTable `json:"tables,omitempty"`
	DBStat bool         `json:"dbstat"`
	// Top is the N every list was cut at.
	Top int `json:"top"`
	// TotalBytes is the database file plus the files below the sessions root.
	TotalBytes int64 `json:"total_bytes"`
}

UsageReport is the result of `suga data usage`.

type UsageSession

type UsageSession struct {
	ID       string `json:"id"`
	Title    string `json:"title,omitempty"`
	DBBytes  int64  `json:"db_bytes"`
	DirBytes int64  `json:"dir_bytes"`
	Bytes    int64  `json:"bytes"`
}

UsageSession is one session in the "largest" list: its ledger bytes and its directory bytes, summed into Bytes.

type UsageSessions

type UsageSessions struct {
	InStore int64 `json:"in_store"`
	Dirs    int64 `json:"dirs"`
	// Tools is every body file of a session, under both names (Tools carries
	// tools.jsonl of version 0.36, BodyFiles says how it splits).
	Tools      SizeStat       `json:"tools"`
	BodyFiles  []NamedStat    `json:"body_files"`
	Outputs    SizeStat       `json:"outputs"`
	OutputsGz  SizeStat       `json:"outputs_gz"`
	Images     SizeStat       `json:"images"`
	Snapshots  SizeStat       `json:"snapshots"`
	Other      SizeStat       `json:"other"`
	Top        []UsageSession `json:"top"`
	Suggestion string         `json:"suggestion,omitempty"`
}

UsageSessions is the sessions root outside the database: the per-session files and the sessions that hold the most.

type UsageTable

type UsageTable struct {
	Name  string `json:"name"`
	Bytes int64  `json:"bytes"`
}

UsageTable is the real page usage of one table or index, from SQLite's dbstat virtual table.

type UsageToolEntries

type UsageToolEntries struct {
	Stub   SizeStat `json:"stub"`
	Inline SizeStat `json:"inline"`
}

UsageToolEntries separates tool results that moved to the session file (entries.body_ref set, only a stub in the ledger) from the ones stored inline.

type VacuumResult

type VacuumResult struct {
	BytesBefore    int64
	BytesAfter     int64
	DBBytesBefore  int64
	DBBytesAfter   int64
	WALBytesBefore int64
	WALBytesAfter  int64
}

VacuumResult reports the database file sizes around a VACUUM. The main file only grows while the data sits in the -wal file, so a caller that wants to show the reclaimed space compares the totals (BytesBefore/BytesAfter).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL