session

package
v0.28.0 Latest Latest
Warning

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

Go to latest
Published: Aug 26, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Index

Constants

View Source
const (
	DefaultSearchFetchTopK = 4
	DefaultSearchPageChars = 6000
)

Deep-research tuning defaults and bounds. Defaults mirror the pipeline's built-in constants; bounds keep user-entered values sane.

Variables

This section is empty.

Functions

func DeleteModelCacheSupport added in v0.26.1

func DeleteModelCacheSupport(database *db.DB, modelID string) error

DeleteModelCacheSupport clears a persisted verdict so the pair is observed again on next use. An empty modelID clears every verdict — the escape hatch for an endpoint that changed behaviour under a stable URL.

func DeleteModelCapability added in v0.6.0

func DeleteModelCapability(database *db.DB, modelID string) error

DeleteModelCapability clears a model's cached capability so it is re-probed on next use. An empty modelID clears every cached capability. Used by the manual-refresh path.

func DeleteModelPreference

func DeleteModelPreference(database *db.DB, id string) error

DeleteModelPreference removes a model preference from the database.

func FinishedNaturally added in v0.26.0

func FinishedNaturally(finish *string) bool

FinishedNaturally reports whether a finish reason means the model was done.

Only three are: the model saying it finished, and the user saying stop. Every other reason — none recorded at all, a request for tools that nothing ran, an error, the output cap — describes a turn that stopped without reaching an end, which is what makes it something to pick back up.

The default is deliberately "not finished". A finish reason this code has never seen is far more likely to be a provider spelling one of the failures its own way than a fourth kind of success, and the cost of the two mistakes is not symmetric: offering a resume that turns out to be unnecessary wastes a click, while withholding one strands the conversation.

func GetModelCacheSupport added in v0.26.1

func GetModelCacheSupport(database *db.DB, modelID, endpoint string) (string, bool, error)

GetModelCacheSupport returns the persisted cache verdict for a model on a specific endpoint. The second return value is false when the pair has not been resolved yet.

func Now

func Now() int64

func SetMemoryConfig added in v0.2.1

func SetMemoryConfig(database *db.DB, c *MemoryConfig) error

SetMemoryConfig upserts the agentic-memory config row (id is always 1). Legacy embed/chat columns are reset to defaults — they are no longer used.

func SetModelCacheSupport added in v0.26.1

func SetModelCacheSupport(database *db.DB, modelID, endpoint, verdict string, observedAt int64) error

SetModelCacheSupport records a resolved cache verdict so later sessions skip the observation window entirely.

func SetModelCapability added in v0.6.0

func SetModelCapability(database *db.DB, c *ModelCapability) error

SetModelCapability upserts a probed capability record for a model.

func SetModelPreference

func SetModelPreference(database *db.DB, p *ModelPreference) error

SetModelPreference upserts a model preference into the database.

func SetProviderConfig added in v0.2.1

func SetProviderConfig(database *db.DB, c *ProviderConfig) error

SetProviderConfig upserts a provider config row.

func SetSearchConfig added in v0.8.0

func SetSearchConfig(database *db.DB, c *SearchConfig) error

SetSearchConfig upserts the singleton config row, clamping the research params before persisting so an invalid client payload can never store bad values.

Types

type ImagePartData added in v0.14.0

type ImagePartData struct {
	MediaType string `json:"mediaType"`
	Data      string `json:"data"`
	Name      string `json:"name,omitempty"`
}

ImagePartData stores a user-uploaded image attachment. Data is base64-encoded image bytes; MediaType is e.g. "image/jpeg" or "image/png". The Name field carries the original filename (optional, for display only).

type InterruptReason added in v0.26.0

type InterruptReason string

InterruptReason classifies why a turn stopped short.

const (
	// InterruptRateLimit is a 429 or a provider quota, the case where waiting
	// is the whole fix. RetryAfter carries when waiting is over, where the
	// provider said.
	InterruptRateLimit InterruptReason = "rate_limit"
	// InterruptServerError is a 5xx or an overloaded provider.
	InterruptServerError InterruptReason = "server_error"
	// InterruptNetwork is a connection that dropped, timed out or was refused.
	InterruptNetwork InterruptReason = "network"
	// InterruptAuth is a rejected key, an expired token, an exhausted balance —
	// resumable, but only once a human has fixed the account behind it.
	InterruptAuth InterruptReason = "auth"
	// InterruptContext is a request too large for the model's window that
	// compaction could not bring back under it.
	InterruptContext InterruptReason = "context"
	// InterruptCrashed marks a turn found unfinished at startup: the process
	// died mid-stream and never got to record anything about why.
	InterruptCrashed InterruptReason = "crashed"
	// InterruptStalled marks a turn that recorded a finish reason but not one
	// the model chose — it asked for a tool and nothing ran it, or it hit the
	// output cap mid-answer. The loop that would have carried on is gone.
	InterruptStalled InterruptReason = "stalled"
	// InterruptFatal is everything a retry cannot help — a malformed request, a
	// model that does not exist, a provider rejecting the tool schema.
	InterruptFatal InterruptReason = "fatal"
)

type Interruption added in v0.26.0

type Interruption struct {
	Reason    InterruptReason `json:"reason"`
	Resumable bool            `json:"resumable"`
	// Detail is a short human-facing sentence naming what to do about it. The
	// raw provider error stays in Error.
	Detail string `json:"detail,omitempty"`
	// RetryAfter is the unix second the provider said to come back at, or 0
	// where it said nothing. Only a rate limit tends to carry one.
	RetryAfter int64 `json:"retryAfter,omitempty"`
	// Step is the loop step the turn died on, for the UI to say how far it got.
	Step int `json:"step,omitempty"`
}

Interruption records why a turn stopped short of finishing and whether picking it up again is worth trying.

It sits beside Error rather than replacing it. Error is the provider's own words, which a user needs to read; this is the classification the resume path acts on, and the two answer different questions.

type MemoryConfig added in v0.2.1

type MemoryConfig struct {
	Enabled   bool  `json:"enabled"`
	UpdatedAt int64 `json:"updatedAt"`
}

MemoryConfig holds the user's agentic-memory configuration stored in the DB.

Embedding is always produced by the inbuilt local embedder (gte-small) — there is no embedder configuration. The synthesis LLM is not configured here either: it uses the session's selected model at call time. So the only persisted knob is whether agentic memory is enabled.

The underlying memory_config table still carries legacy embed/chat columns from earlier releases; they are no longer read or written by this struct but are retained in the schema for migration safety.

func GetMemoryConfig added in v0.2.1

func GetMemoryConfig(database *db.DB) (*MemoryConfig, error)

GetMemoryConfig returns the stored agentic-memory config. If the row does not exist, agentic memory defaults to enabled: the inbuilt local embedder (gte-small) needs zero setup — no API key, no external service — so memory is on out of the box. A user who has explicitly turned memory off has a persisted row with enabled = 0, which is still honored.

func MaskedMemoryConfig added in v0.2.1

func MaskedMemoryConfig(c *MemoryConfig) *MemoryConfig

MaskedMemoryConfig returns a copy of c. With the embed/chat fields gone there are no secrets to mask, but the function is retained for API compatibility.

type MessageID

type MessageID = id.MessageID

func NewMessageID

func NewMessageID() MessageID

type MessageInfo

type MessageInfo struct {
	ID        MessageID    `json:"id"`
	SessionID SessionID    `json:"sessionId"`
	Role      MessageRole  `json:"role"`
	Agent     string       `json:"agent,omitempty"`
	ParentID  *MessageID   `json:"parentId,omitempty"`
	Finish    *string      `json:"finish,omitempty"`
	Cost      float64      `json:"cost,omitempty"`
	Tokens    *TokenCounts `json:"tokens,omitempty"`
	Error     *string      `json:"error,omitempty"`
	// Interrupted is set when a loop stopped part-way through this turn rather
	// than because the model finished. It is what a resume decides from.
	Interrupted *Interruption `json:"interrupted,omitempty"`
	CreatedAt   int64         `json:"createdAt"`
}

func (*MessageInfo) CanResume added in v0.26.0

func (m *MessageInfo) CanResume() bool

CanResume reports whether a message is one a resume should act on.

type MessageRole

type MessageRole string
const (
	RoleUser      MessageRole = "user"
	RoleAssistant MessageRole = "assistant"
)

type MessageWithParts

type MessageWithParts struct {
	Info  MessageInfo `json:"info"`
	Parts []Part      `json:"parts"`
}

type ModelCapability added in v0.6.0

type ModelCapability struct {
	ModelID        string `json:"modelId"`
	SupportsImages bool   `json:"supportsImages"`
	ProbedAt       int64  `json:"probedAt"`
}

ModelCapability is a probed/known capability record for a model, persisted so the image-support probe runs at most once per model (until manually refreshed).

func GetModelCapability added in v0.6.0

func GetModelCapability(database *db.DB, modelID string) (*ModelCapability, bool, error)

GetModelCapability returns the persisted capability record for a model. The second return value is false when no record exists (not yet probed).

type ModelPreference

type ModelPreference struct {
	ID          string `json:"id"`
	Enabled     bool   `json:"enabled"`
	ProviderID  string `json:"providerId"`
	DisplayName string `json:"displayName"`
	IsCustom    bool   `json:"isCustom"`
	// Collection is an optional group name for custom models so OpenAI-compatible
	// providers added through the OpenAI provider (Gemini, DeepSeek, Groq, …) can
	// be grouped together in the UI instead of all collapsing under "OpenAI".
	// Empty for built-in models and legacy custom models (falls back to providerId).
	Collection string `json:"collection"`
	CreatedAt  int64  `json:"createdAt"`
	UpdatedAt  int64  `json:"updatedAt"`
}

func GetModelPreferences

func GetModelPreferences(database *db.DB) ([]*ModelPreference, error)

GetModelPreferences returns all model preference overrides from the database.

type ModelPreferenceStore

type ModelPreferenceStore struct{}

type Part

type Part struct {
	ID        PartID          `json:"id"`
	MessageID MessageID       `json:"messageId"`
	SessionID SessionID       `json:"sessionId"`
	Type      PartType        `json:"type"`
	Data      json.RawMessage `json:"data"`
	CreatedAt int64           `json:"createdAt"`
	UpdatedAt int64           `json:"updatedAt"`
}

type PartID

type PartID = id.PartID

func NewPartID

func NewPartID() PartID

type PartType

type PartType string
const (
	PartText      PartType = "text"
	PartTool      PartType = "tool"
	PartReasoning PartType = "reasoning"
	PartFile      PartType = "file"
	PartImage     PartType = "image"
)

type PermissionID

type PermissionID = id.PermissionID

func NewPermissionID

func NewPermissionID() PermissionID

type ProviderConfig added in v0.2.1

type ProviderConfig struct {
	ProviderID string `json:"providerId"`
	APIKey     string `json:"apiKey"`
	BaseURL    string `json:"baseUrl"`
	UpdatedAt  int64  `json:"updatedAt"`
}

ProviderConfig holds credentials for a single LLM provider stored in the DB.

func GetAllProviderConfigs added in v0.2.1

func GetAllProviderConfigs(database *db.DB) ([]*ProviderConfig, error)

GetAllProviderConfigs returns stored configs for all providers.

func GetProviderConfig added in v0.2.1

func GetProviderConfig(database *db.DB, providerID string) (*ProviderConfig, error)

GetProviderConfig returns the stored config for a provider. Returns a zero-value config (empty fields) when no row exists.

func MaskedProviderConfig added in v0.2.1

func MaskedProviderConfig(c *ProviderConfig) *ProviderConfig

MaskedProviderConfig returns a copy with the API key replaced by a sentinel so it can be sent to the UI without leaking the real value.

type ReasoningPartData

type ReasoningPartData struct {
	Text      string `json:"text"`
	Signature string `json:"signature,omitempty"`
}

type SearchConfig added in v0.8.0

type SearchConfig struct {
	Enabled        bool  `json:"enabled"`
	UseRealProfile bool  `json:"useRealProfile"`
	FetchTopK      int   `json:"fetchTopK"`
	PageChars      int   `json:"pageChars"`
	UpdatedAt      int64 `json:"updatedAt"`
}

SearchConfig holds the global web-search toggle plus the deep-research pipeline tuning knobs (pages fetched, per-page size).

func GetSearchConfig added in v0.8.0

func GetSearchConfig(database *db.DB) (*SearchConfig, error)

GetSearchConfig returns the stored config. If no row exists it returns the defaults (disabled, with default research params). Research params are always clamped so callers never receive zero/invalid values.

type Session

type Session struct {
	ID                SessionID `json:"id"`
	ProjectID         string    `json:"projectId"`
	Directory         string    `json:"directory"`
	Title             string    `json:"title"`
	Model             string    `json:"model,omitempty"`
	SessionType       string    `json:"sessionType,omitempty"`
	Permission        string    `json:"permission,omitempty"`
	CompactionSummary string    `json:"compactionSummary,omitempty"`
	MemoryTokensSaved int       `json:"memoryTokensSaved,omitempty"`
	CreatedAt         int64     `json:"createdAt"`
	UpdatedAt         int64     `json:"updatedAt"`
}

type SessionID

type SessionID = id.SessionID

func NewSessionID

func NewSessionID() SessionID

type Store

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

func NewStore

func NewStore(database *db.DB) *Store

func (*Store) Create

func (s *Store) Create(session *Session) error

func (*Store) CreateMessage

func (s *Store) CreateMessage(msg *MessageInfo) error

func (*Store) CreatePart

func (s *Store) CreatePart(part *Part) error

func (*Store) DB added in v0.6.0

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

DB returns the underlying database handle, used by helpers that operate on other tables (e.g. model capability records).

func (*Store) Delete

func (s *Store) Delete(id SessionID) error

func (*Store) DeleteMessage added in v0.19.1

func (s *Store) DeleteMessage(messageID MessageID) error

DeleteMessage removes a message and all of its parts. Foreign-key cascade handles part deletion automatically. Used to clean up partial assistant messages left behind when mid-loop guidance cancels a text-only stream — keeping them would produce two consecutive assistant role messages on the next prompt, which the Anthropic and OpenAI APIs reject with a 400.

func (*Store) Get

func (s *Store) Get(id SessionID) (*Session, error)

func (*Store) GetMessage

func (s *Store) GetMessage(messageID MessageID) (*MessageWithParts, error)

func (*Store) GetMessages

func (s *Store) GetMessages(sessionID SessionID, before MessageID, limit int) ([]*MessageWithParts, error)

func (*Store) GetPart

func (s *Store) GetPart(partID PartID) (*Part, error)

func (*Store) GetParts

func (s *Store) GetParts(messageID MessageID) ([]Part, error)

func (*Store) List

func (s *Store) List(directory string) ([]*Session, error)

func (*Store) ListAll added in v0.23.0

func (s *Store) ListAll() ([]*Session, error)

ListAll returns every session row regardless of directory or type, including the note/index/search sessions List hides. Agentic memory uses it to backfill project identity onto nodes written before that column existed.

func (*Store) Update

func (s *Store) Update(session *Session) error

func (*Store) UpdateCompactionSummary

func (s *Store) UpdateCompactionSummary(id SessionID, summary string) error

UpdateCompactionSummary updates only the compaction_summary column for a session, avoiding the race condition of overwriting other fields (e.g., title, model) that may have changed concurrently.

func (*Store) UpdateMemoryTokensSaved added in v0.2.1

func (s *Store) UpdateMemoryTokensSaved(id SessionID, delta int) error

UpdateMemoryTokensSaved atomically increments memory_tokens_saved by delta (may be negative). delta is clamped above at 1_000_000_000 to prevent overflow; negative values are preserved so callers can track memory overhead accurately.

func (*Store) UpdateMessage

func (s *Store) UpdateMessage(msg *MessageInfo) error

func (*Store) UpdatePart

func (s *Store) UpdatePart(part *Part) error

type TextPartData

type TextPartData struct {
	Text string `json:"text"`
}

type TokenCounts

type TokenCounts struct {
	Total      int `json:"total,omitempty"`
	Input      int `json:"input,omitempty"`
	Output     int `json:"output,omitempty"`
	Reasoning  int `json:"reasoning,omitempty"`
	CacheRead  int `json:"cacheRead,omitempty"`
	CacheWrite int `json:"cacheWrite,omitempty"`
}

type ToolImage added in v0.6.0

type ToolImage struct {
	MediaType string `json:"mediaType"`
	Data      string `json:"data"`
}

ToolImage is an image produced by a tool, persisted so the model can be re-sent the image on history replay. Data is base64-encoded image bytes.

type ToolPartData

type ToolPartData struct {
	Tool   string    `json:"tool"`
	CallID string    `json:"callId"`
	State  ToolState `json:"state"`
}

type ToolState

type ToolState struct {
	Status   ToolStatus      `json:"status"`
	Input    json.RawMessage `json:"input"`
	Output   *string         `json:"output,omitempty"`
	Error    *string         `json:"error,omitempty"`
	Title    *string         `json:"title,omitempty"`
	Metadata json.RawMessage `json:"metadata,omitempty"`
	Image    *ToolImage      `json:"image,omitempty"`
	Time     ToolTime        `json:"time"`
}

type ToolStatus

type ToolStatus string
const (
	ToolPending   ToolStatus = "pending"
	ToolRunning   ToolStatus = "running"
	ToolCompleted ToolStatus = "completed"
	ToolError     ToolStatus = "error"
	ToolDenied    ToolStatus = "denied"
)

type ToolTime

type ToolTime struct {
	Start int64 `json:"start,omitempty"`
	End   int64 `json:"end,omitempty"`
}

Jump to

Keyboard shortcuts

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