memory

type ActionTool = toolmeta.ActionTool

type ChangeEntry struct {
	ID                  string
	UserID              string
	AgentID             string
	SessionID           string
	Scope               string // "profile", "soul", "constraint", "skill", "compaction"
	Action              string // "create", "update", "delete", "deprecate", "compact"
	Source              ChangeSource
	MemoryVersionBefore *int64
	MemoryVersionAfter  *int64
	BeforeText          string
	AfterText           string
	CreatedAt           string
}

type ChangeSource string

type ChangelogCursor struct {
	CreatedAt time.Time
	ID        string
}

type ChangelogPageReader interface {
	ReadChangelogPage(ctx context.Context, userID string, agentID string, scope string, cursor *ChangelogCursor, limit int) ([]ChangeEntry, error)
}

type ChangelogReader interface {
	// ReadChangelog returns the last N changelog entries for a given scope.
	ReadChangelog(ctx context.Context, userID string, agentID string, scope string, limit int) ([]ChangeEntry, error)
}

type ChangelogWriter interface {
	// WriteChangelog records a memory change.
	WriteChangelog(ctx context.Context, entry ChangeEntry) error
}

type CompactionMode int

type CompactionResult struct {
	LeafSummariesCreated      int
	CondensedSummariesCreated int
	MessagesCompacted         int
	TokensBefore              int
	TokensAfter               int
	Duration                  time.Duration
}

type Compactor interface {
	// NeedsCompaction returns true if the session's context token count exceeds
	// threshold, an absolute token count.
	NeedsCompaction(ctx context.Context, session Session, threshold float64) bool

	// Compact runs the compaction algorithm on the session.
	// Incremental mode runs a single summarisation pass (fast, called automatically).
	// Full mode runs repeated passes until no further reduction is possible
	// (slow, called on demand e.g. via /compact slash command).
	Compact(ctx context.Context, session Session, mode CompactionMode) (*CompactionResult, error)
}

type ConstraintEntry struct {
	ID        string `json:"id"`
	Text      string `json:"text"`
	CreatedAt string `json:"created_at"`
}

type ConstraintStore interface {
	// GetConstraints returns all active constraints for the (userID, agentID) pair.
	GetConstraints(ctx context.Context, userID string, agentID string) ([]ConstraintEntry, error)

	// AddConstraint adds a new constraint with a generated UUID-like ID.
	// Returns the updated list of constraints.
	AddConstraint(ctx context.Context, userID string, agentID string, text string) ([]ConstraintEntry, error)

	// RemoveConstraint removes the constraint with the given ID.
	// Returns the updated list of constraints.
	RemoveConstraint(ctx context.Context, userID string, agentID string, id string) ([]ConstraintEntry, error)
}

type CurrentSpeaker struct {
	Platform       string // source platform (telegram, feishu, web, ...)
	PlatformUserID string // platform sender id / Web auth user id; lookup/audit only
	DisplayName    string // sender display name when available
	UserID         string // resolved Stella auth user id when linked; empty when unlinked
}

type DeferredGroupTurn struct {
	Session              Session
	OwnRows              []ai.Message
	TriggerSeq           int64
	OriginGroupMessageID string
	Complete             bool
}

type DescribeResult struct {
	SummaryID       string
	Kind            string     // "leaf" or "condensed"
	Depth           int        // 0 = leaf, 1+ = condensed
	Content         string     // the summary text
	EarliestAt      *time.Time // timestamp of oldest source message
	LatestAt        *time.Time // timestamp of newest source message
	DescendantCount int        // total original messages this summary covers
	ParentIDs       []string   // summaries that contain this one (condensed parents)
	ChildIDs        []string   // summaries or messages this one was built from
}

type ExpandChild struct {
	SummaryID string
	Kind      string
	Depth     int
	Content   string
}

type ExpandMessage struct {
	MessageID string
	Role      string
	Content   string
	CreatedAt time.Time
}

type ExpandResult struct {
	SummaryID string
	// For leaf summaries: the original source messages.
	Messages []ExpandMessage
	// For condensed summaries: the child summaries.
	Children []ExpandChild
}

type Explorer interface {
	// Describe returns metadata and lineage for a summary ID.
	Describe(ctx context.Context, summaryID string) (*DescribeResult, error)

	// Expand drills into a summary:
	//   - For leaf summaries: returns the original source messages
	//   - For condensed summaries: returns the child summaries
	// tokenCap limits how many tokens of content are returned.
	Expand(ctx context.Context, summaryID string, tokenCap int) (*ExpandResult, error)
}

type Fact struct {
	ID         string          `json:"id"`
	Subject    FactSubject     `json:"subject"`
	Scope      string          `json:"scope"`
	UserID     string          `json:"user_id"`
	AgentID    string          `json:"agent_id"`
	Content    string          `json:"content"`
	Status     FactStatus      `json:"status"`
	Metadata   json.RawMessage `json:"metadata"`
	Supersedes string          `json:"supersedes,omitempty"`
	Version    int64           `json:"version"`
	Source     ChangeSource    `json:"source"`
	CreatedAt  time.Time       `json:"created_at"`
	UpdatedAt  time.Time       `json:"updated_at"`
}

type FactStatus string

type FactStore interface {
	ListActiveFacts(ctx context.Context, userID string, agentID string, subject FactSubject) ([]Fact, error)
}

type FactSubject string

type FactWrite struct {
	UserID     string
	AgentID    string
	Subject    FactSubject
	Content    string
	Metadata   json.RawMessage
	Supersedes string
	Source     ChangeSource
}

type GroupCursorCommitter interface {
	CommitGroupCursor(ctx context.Context, session Session, triggerSeq int64) error
}

type GroupRecallResult struct {
	ID               string
	Seq              int64
	ActorType        string
	ActorDisplayName string
	Content          string
	Snippet          string
	Score            float64
	OccurredAt       time.Time
}

type GroupRecallSource interface {
	SearchGroupRecall(ctx context.Context, groupID string, triggerSeq int64, query string, limit int) ([]GroupRecallResult, error)
	ReadGroupRecall(ctx context.Context, groupID string, triggerSeq int64, messageID string, tokenCap int) ([]GroupRecallResult, bool, error)
}

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

type GroupWake struct {
	// Reason is the triage outcome that let this turn run.
	Reason string
	// HeldUpToSeq is set when this run follows a HOLD: a peer posted while the
	// agent was drafting, and everything up to this seq is new since then.
	HeldUpToSeq int64
	// MentionSeq is the earliest unconsumed event that addressed this agent.
	// It lets bounded context retain the reason for a coalesced wake.
	MentionSeq int64
}

type Handler interface {
	Read(context.Context, MemoryReadInput) (any, error)
	Search(context.Context, MemorySearchInput) (any, error)
}

type InboxAppender interface {
	AppendInboxInput(ctx context.Context, session Session, inboxID string, msg ai.Message) error
}

type KnowledgeUsageTracker interface {
	TouchKnowledgeUsage(ctx context.Context, userID string, agentID string, factIDs []string) error
}

type LLMSummarizer struct {
	// Generate calls the LLM with the given prompt and returns the response text.
	Generate func(ctx context.Context, prompt string) (string, error)
}

type ListOptions struct {
	AgentID         string // filter by agent (empty = all)
	UserID          string // filter by user (empty = all)
	GuestID         string // filter by guest; empty excludes guest-owned sessions
	Kind            string // filter by kind (empty = all)
	Channel         string // filter by durable channel binding (empty = all)
	ProjectID       string // filter by project (empty = all)
	ProjectIDIsNull bool   // when true, require project_id IS NULL
	IncludeArchived bool
	ExcludeInternal bool // hide task/delegate worker sessions from user-facing lists
	Limit           int  // 0 = no limit
	Offset          int  // skip first N matching results
}

type MemoryReadInput struct {
	Ref      string `json:"ref,omitempty"`
	TokenCap int    `json:"token_cap,omitempty"`
}

type MemorySearchInput struct {
	Limit int    `json:"limit,omitempty"`
	Q     string `json:"q,omitempty"`
}

type MessageDetail struct {
	MessageID         string    `json:"message_id"`
	Role              string    `json:"role"`
	Content           string    `json:"content"`
	OccurredAt        time.Time `json:"occurred_at"`        // when the message happened
	SessionID         string    `json:"session_id"`         // origin session for traceability
	ConversationTitle string    `json:"conversation_title"` // human-readable origin label (may be empty)
}

type MessageReader interface {
	GetMessage(ctx context.Context, messageID string) (*MessageDetail, error)
}

type ProfileEntry struct {
	ID        string `json:"id"`
	Text      string `json:"text"`
	Source    string `json:"source"`     // "manual" or "auto"
	CreatedAt string `json:"created_at"` // RFC3339
}

type ProfileEntryStore interface {
	GetProfileEntries(ctx context.Context, userID string, agentID string) ([]ProfileEntry, error)
}

type ProfileStore interface {
	// GetProfile returns the current user profile for the (userID, agentID) pair.
	// Returns ("", nil) if no profile exists yet (not an error).
	GetProfile(ctx context.Context, userID string, agentID string) (string, error)

	// SetProfile overwrites the user profile for the (userID, agentID) pair.
	// Callers are responsible for merging new content with existing content
	// before calling SetProfile — this method always replaces, never appends.
	SetProfile(ctx context.Context, userID string, agentID string, content string) error

	// GetAgentSoul returns the agent soul for the (userID, agentID) pair.
	// The soul defines the agent's identity, personality, and behavior as
	// customised by this specific user. Returns ("", nil) if not set.
	GetAgentSoul(ctx context.Context, userID string, agentID string) (string, error)

	// SetAgentSoul overwrites the agent soul for the (userID, agentID) pair.
	// Callers are responsible for merging; this method always replaces.
	SetAgentSoul(ctx context.Context, userID string, agentID string, content string) error
}

type Provider interface {
	// Name returns the plugin identifier (e.g. "lcm", "simple").
	// Used in logs and admin UI.
	Name() string

	// Bootstrap ensures the session is initialized and ready for use.
	// Called once at the start of every chat turn before any Append or Assemble.
	// Implementations use this to create conversation records, initialize caches,
	// or establish remote connections for the session.
	Bootstrap(ctx context.Context, session Session) error

	// Append persists one or more messages to the session's event log.
	// Ordinary sessions receive canonical image references and must reject raw
	// provider image bytes. Group sessions may retain their legacy inline codec.
	// Messages must be appended in the order they arrive.
	// Callers pass all messages from a single turn together so implementations
	// can store them in a single atomic transaction if they choose.
	//
	// Concurrency: implementations MUST be safe for concurrent Append calls
	// on different sessions. Concurrent Append calls on the SAME session
	// MUST be serialised by the implementation (see Concurrency Contract).
	Append(ctx context.Context, session Session, msgs ...ai.Message) error

	// Assemble builds the context window to send to the LLM.
	// budget: maximum number of tokens the returned messages may consume.
	// freshTail: number of recent user turns to prefer verbatim. Implementations
	//   may apply safety caps so oversized tails do not consume the whole budget.
	// Returns messages in chronological order (oldest first).
	// Older content that does not fit in the budget is either summarised
	// (if the plugin supports Compactor) or omitted.
	Assemble(ctx context.Context, session Session, budget, freshTail int) ([]ai.Message, error)

	// Stats returns basic statistics about a session's memory state.
	// Used by the admin endpoints; no model-facing tool exposes it.
	// Returns zero-value stats (not an error) if the session does not exist.
	Stats(ctx context.Context, session Session) (SessionStats, error)

	// Close releases any resources held by the provider (DB connections, caches, etc.).
	// Called on shutdown. Must be safe to call multiple times.
	Close() error
}

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

type RecallDocument struct {
	Reference         RecallReference
	Content           string
	Role              string
	Authority         string
	OccurredAt        time.Time
	SessionID         string
	ConversationTitle string
	Summary           *RecallSummaryDetail
}

type RecallFragment struct {
	Reference  RecallReference
	Role       string
	Authority  string
	Kind       string
	Depth      *int
	Content    string
	OccurredAt time.Time
}

type RecallReference struct {
	Kind      string
	ID        string
	SessionID string
}

type RecallSearchResult struct {
	Reference         RecallReference
	Content           string
	Score             float64
	OccurredAt        time.Time
	SessionID         string
	ConversationTitle string
}

type RecallSource interface {
	SearchRecall(ctx context.Context, authority authz.Authority, agentID, query string, limit int) ([]RecallSearchResult, error)
	ReadRecall(ctx context.Context, authority authz.Authority, agentID string, ref RecallReference, tokenCap int) (RecallDocument, error)
}

type RecallSummaryDetail struct {
	Kind            string
	Depth           int
	DescendantCount int
	EarliestAt      *time.Time
	LatestAt        *time.Time
	Parents         []RecallReference
	Children        []RecallReference
	Expanded        []RecallFragment
}

type ReviewHistoryReader interface {
	LoadReviewHistory(ctx context.Context, sessionID string) ([]ReviewMessage, error)
}

type ReviewMessage struct {
	ID       string
	FirstSeq int64
	LastSeq  int64
	Message  ai.Message
}

type Reviewer interface {
	// BuildReviewContext returns a text representation of the conversation
	// suitable for passing to a reviewer agent's prompt.
	//
	// since: if non-zero, only include content created after this time.
	//   The provider should include prior context (e.g. summaries from before
	//   this timestamp) to give the reviewer enough background.
	//   If zero, include all content.
	//
	// Returns ("", nil) if there is no content to review.
	BuildReviewContext(ctx context.Context, session Session, since time.Time) (string, error)
}

type SearchQuery struct {
	Text  string      // search term (keyword or natural language depending on plugin)
	Scope SearchScope // which layer of storage to search
	Limit int         // max results (default 20)
}

type SearchResult struct {
	SourceType        string    `json:"source_type"`        // "message" or "summary"
	SourceID          string    `json:"source_id"`          // message ID or summary ID
	Content           string    `json:"content"`            // snippet of the matching content (truncated at ~500 chars)
	Score             float64   `json:"score"`              // relevance, higher is better: pg_search BM25 for a single-scope query, RRF fusion score when messages and summaries are merged
	OccurredAt        time.Time `json:"occurred_at"`        // when the underlying content actually happened
	SessionID         string    `json:"session_id"`         // origin session for traceability
	ConversationTitle string    `json:"conversation_title"` // human-readable origin label (may be empty)
}

type SearchScope int

type Searcher interface {
	Search(ctx context.Context, session Session, query SearchQuery) ([]SearchResult, error)
}

type Session struct {
	ID      string // unique session key (e.g. "default:cli:<uuid>:main")
	AgentID string // agent this session belongs to (e.g. "default")
	UserID  string // internal user ID (empty for anonymous/legacy)
	Channel string // originating channel (e.g. "cli", "telegram")
	GroupID string // non-empty for group sessions; assembles history from event log instead of ctx_message
	GuestID string // non-empty for a persistent channel guest; equals UserID
}

type SessionActivityStore interface {
	MarkSessionTurnStarted(ctx context.Context, session Session) (bool, error)
	MarkSessionTurnCompleted(ctx context.Context, session Session, result SessionTurnResult) (bool, error)
	MarkSessionViewed(ctx context.Context, session Session) (bool, error)
}

type SessionInfo struct {
	ID                  string
	AgentID             string
	UserID              string
	GroupID             string // non-empty for group sessions; runtime uses this to isolate identity surfaces
	GuestID             string // non-empty for a persistent channel guest; equals UserID
	Channel             string
	Kind                string // session kind: main, chat, scheduler, task
	ProjectID           string // set for project-scoped sessions
	Title               string // auto-generated from first message
	CreatedAt           time.Time
	LastActive          time.Time
	LastTurnStartedAt   time.Time
	LastTurnCompletedAt time.Time
	LastTurnResult      SessionTurnResult
	LastViewedAt        time.Time
	Archived            bool
	// LatestSeq is the latest persisted message sequence when supplied by a
	// review-aware listing. Zero means the provider has no stable sequence.
	LatestSeq int64
}

type SessionManager interface {
	// SaveInfo creates a session or updates metadata while it remains active.
	// Archived is only honored when creating a new row; lifecycle transitions
	// for an existing row must use ArchiveInfo or RotateInfo.
	SaveInfo(ctx context.Context, info SessionInfo) error

	// ArchiveInfo atomically transitions an active session to archived. It
	// reports false without writing when the scoped session is already inactive.
	ArchiveInfo(ctx context.Context, info SessionInfo) (bool, error)

	// RotateInfo archives expectedSessionID and creates successor as one atomic
	// unit, so a durable binding is never left without an active session and a
	// one-active-session-per-binding index is never violated mid-rotation.
	// It returns ErrStaleRotation, with nothing persisted, when expectedSessionID
	// is no longer active or no longer matches successor's binding.
	RotateInfo(ctx context.Context, expectedSessionID string, successor SessionInfo) error

	// TouchActiveInfo records a running turn's metadata — its last-active
	// timestamp, and a title for a session that has none — against a session that
	// is still active, and reports false without writing when it is not.
	//
	// It exists because SaveInfo cannot serve the turn path: a turn holds the
	// snapshot it resolved at the start, a rotation can archive that session
	// while the turn runs, and replaying the snapshot would un-archive a session
	// the chat has already left. Checking first and then saving only narrows the
	// race; this is the guard and the write in one statement.
	TouchActiveInfo(ctx context.Context, info SessionInfo) (bool, error)

	// LoadInfo retrieves metadata for a single session.
	LoadInfo(ctx context.Context, sessionID string) (SessionInfo, error)

	// ListInfo lists sessions matching the options.
	ListInfo(ctx context.Context, opts ListOptions) ([]SessionInfo, error)

	// LoadHistory returns the complete raw message history for a session
	// in chronological order. Used by the Web UI viewer and export.
	LoadHistory(ctx context.Context, sessionID string) ([]ai.Message, error)
}

type SessionSnapshot struct {
	SessionID string
	UserID    string
	AgentID   string
	Version   int64
	// UpdatedAt is the wall-clock time when this snapshot was last advanced.
	// It remains for legacy skill-backed knowledge filtering; v1 facts use
	// Version as their snapshot clock.
	UpdatedAt time.Time
}

type SessionSnapshotStore interface {
	// GetOrCreateSessionSnapshot returns the snapshot for the session, creating it
	// if it doesn't exist. When creating, freezes the current ctx_agent_memory.version.
	GetOrCreateSessionSnapshot(ctx context.Context, sessionID string, userID string, agentID string) (SessionSnapshot, error)

	// AdvanceSessionSnapshot updates the snapshot version to the current
	// ctx_agent_memory.version for (userID, agentID).
	// Called after front-end memory writes so the current session sees the update.
	AdvanceSessionSnapshot(ctx context.Context, sessionID string, userID string, agentID string) error
}

type SessionStats struct {
	MessageCount int       // total messages stored for this session
	TokenCount   int       // estimated total tokens across all stored messages
	SummaryCount int       // number of summaries (0 for providers without Compactor)
	OldestAt     time.Time // timestamp of the earliest message (zero if empty)
	NewestAt     time.Time // timestamp of the most recent message (zero if empty)
}

type SessionTurnResult string

type StaticSummarizer struct {
	Response string
	Err      error
}

type SummarizeOptions struct {
	IsCondensed  bool
	Depth        int
	Aggressive   bool
	Previous     string // previous summary for continuity
	TargetTokens int
}

type Summarizer interface {
	Summarize(ctx context.Context, text string, opts SummarizeOptions) (string, error)
}

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

type TxGroupCommitter interface {
	CommitGroupTurn(context.Context, *sqlc.Queries, DeferredGroupTurn) error
}

type VersionedConstraintStore interface {
	GetConstraintsAt(ctx context.Context, userID string, agentID string, version int64) ([]ConstraintEntry, error)
}

type VersionedFactStore interface {
	ListActiveFactsAt(ctx context.Context, userID string, agentID string, subject FactSubject, version int64) ([]Fact, error)
}

type VersionedProfileStore interface {
	GetProfileAt(ctx context.Context, userID string, agentID string, version int64) (string, error)
	GetAgentSoulAt(ctx context.Context, userID string, agentID string, version int64) (string, error)
}