session

package
v1.2.92 Latest Latest
Warning

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

 Go to latest Published: Aug 23, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Index

Constants

View Source 
const CurrentVersion = 3

Variables

View Source 
var (
	ErrForkSessionNotFound     = errors.New("source session not found")
	ErrForkSessionActive       = errors.New("source session is active")
	ErrForkNoCompletedTurn     = errors.New("source session has no completed conversation turn")
	ErrForkUnavailable         = errors.New("fork boundary is unavailable")
	ErrForkInvalidBoundary     = errors.New("fork boundary is invalid")
	ErrForkUnsupportedEntry    = errors.New("fork contains unsupported entry")
	ErrForkIdempotencyRequired = errors.New("fork request ID is required")
	ErrForkIdempotencyTooLong  = errors.New("fork request ID is too long")
	ErrForkIdempotencyConflict = errors.New("fork idempotency request conflicts")
)
View Source 
var (
	ErrRuntimeLeaseBusy = errors.New("session runtime lease is held by another process")
	ErrRuntimeLeaseLost = errors.New("session runtime lease was lost")
)
View Source 
var ErrConversationTurnNotOpen = errors.New("conversation turn is not open")
View Source 
var ErrSessionIDExists = errors.New("session ID already exists")

ErrSessionIDExists means a new session attempted to reuse an existing ID. A duplicate must be rejected: updating the sessions row would merge the new header with the old entries and create a forked conversation.

View Source 
var ErrSessionModified = errors.New("session was modified by another process")

Functions

func AbandonInterruptedToolExecutionRecords added in v1.1.77 

func AbandonInterruptedToolExecutionRecords(sessionDir, sessionID, localTurnID string) (int64, error)

AbandonInterruptedToolExecutionRecords marks uncertain executions as explicitly abandoned. It never retries a tool or invents a tool output; callers use it only after they have established that no runtime owns the session lock. This makes a subsequent user-submitted run a new operation instead of silently replaying a potentially side-effecting call.

func BindSession added in v1.1.77 

func BindSession(sessionDir, sessionID, channelType, channelID string) error

func CloseDatabases added in v1.1.73 

func CloseDatabases() error

CloseDatabases checkpoints and closes all process-owned session connections.

func CompareAndSwapResponseSessionState added in v1.1.77 

func CompareAndSwapResponseSessionState(sessionDir string, state ResponseSessionState, expectedVersion int64) (bool, error)

CompareAndSwapResponseSessionState advances a session lineage only when the caller observed expectedVersion. It prevents two concurrent turns from silently branching a previous_response_id chain.

func ConsumeESMGuidance added in v1.2.83 

func ConsumeESMGuidance(sessionDir, sessionID string, ids []string) error

func CountAll added in v1.1.77 

func CountAll(sessionDir string) (int, error)

func CountWithMessages added in v1.2.83 

func CountWithMessages(sessionDir string, opts ...ListOption) (int, error)

CountWithMessages returns the number of sessions that contain at least one persisted conversation message. Empty sessions can be created transiently during startup or request setup and are not user-visible history.

func CreateExecutionIntentAndSessionRun added in v1.2.83 

func CreateExecutionIntentAndSessionRun(sessionDir string, intent ExecutionIntent, run SessionRun) error

CreateExecutionIntentAndSessionRun atomically admits an immutable execution intent with its first or linked Run. Runtime-owned callers use this instead of writing the two records independently, so a reconnect can always resolve a durable Run back to the request that created it.

func CreateExecutionIntentAndSessionRunEvent added in v1.2.83 

func CreateExecutionIntentAndSessionRunEvent(sessionDir string, intent ExecutionIntent, run SessionRun, event SessionRunEvent) (string, error)

CreateExecutionIntentAndSessionRunEvent atomically admits an immutable intent, its Run row, and (when supplied) the canonical started event. This prevents a process loss between the intent/run write and event publication from creating an accepted execution with no replay anchor.

func CreateExecutionIntentAndSessionRunEventWithTurn added in v1.2.92 

func CreateExecutionIntentAndSessionRunEventWithTurn(sessionDir string, intent ExecutionIntent, run SessionRun, event SessionRunEvent, turn ConversationTurn) (string, error)

CreateExecutionIntentAndSessionRunEventWithTurn atomically admits an immutable intent, its Run/event, and the conversation turn boundary.

func CreateSessionRun added in v1.2.83 

func CreateSessionRun(sessionDir string, run SessionRun) error

CreateSessionRun inserts one canonical run row. Unlike SaveSessionRun, this method never overwrites an existing identity; Runtime-owned lifecycle code must treat duplicate run IDs as an admission error.

func CreateSessionRunAndEvent added in v1.2.83 

func CreateSessionRunAndEvent(sessionDir string, run SessionRun, event SessionRunEvent) (string, error)

CreateSessionRunAndEvent atomically inserts a new canonical Run and its first event. Retry attempts use this path so a process loss cannot leave a durable attempt without a replay anchor.

func CreateSessionRunAndEventWithTurn added in v1.2.92 

func CreateSessionRunAndEventWithTurn(sessionDir string, run SessionRun, event SessionRunEvent, turn ConversationTurn) (string, error)

CreateSessionRunAndEventWithTurn atomically admits a Run, its first event, and a conversation turn boundary when the Run produces transcript output.

func DeleteProject added in v1.2.83 

func DeleteProject(sessionDir, id string) error

func DeleteSession 

func DeleteSession(path string, sessionDir string) error

DeleteSession deletes a session file if it is under sessionDir.

func EndConversationTurn added in v1.2.92 

func EndConversationTurn(sessionDir, sessionID, turnID, status, stopReason string, endedAt time.Time) error

EndConversationTurn atomically writes turn/end and closes its boundary row.

func EnsureCurrentSchema added in v1.1.73 

func EnsureCurrentSchema(db *sql.DB) error

EnsureCurrentSchema creates the current schema only for an empty database. Existing databases are validated but never migrated or otherwise modified.

func FinishSessionRunAndConversationTurn added in v1.2.92 

func FinishSessionRunAndConversationTurn(sessionDir string, run SessionRun, event SessionRunEvent, turnID, turnStatus, stopReason string) (string, error)

FinishSessionRunAndConversationTurn atomically closes a conversation turn, its Run row, and the terminal Run event. A missing turn is tolerated for recovery/idempotent retries because an Agent may already have emitted the boundary before Runtime terminalization.

func GenerateID 

func GenerateID() string

GenerateID generates a random 8-character hex ID.

func GetChannelToolGeneration added in v1.1.77 

func GetChannelToolGeneration(sessionDir, sessionID string) (int64, error)

func LatestAdditionalDirectoriesByID added in v1.2.90 

func LatestAdditionalDirectoriesByID(sessionDir, sessionID string) ([]string, error)

LatestAdditionalDirectoriesByID reads the replayed directory binding for a session without exposing SQLite details to protocol adapters.

func LatestSessionRunEventSeq added in v1.2.83 

func LatestSessionRunEventSeq(sessionDir, runID string) (int64, error)

LatestSessionRunEventSeq returns the durable replay cursor for one Run. Callers use it to reconcile a disconnected adapter before requesting only the missing portion of the session event stream.

func LatestSessionTitle added in v1.2.83 

func LatestSessionTitle(sessionDir, sessionID string) (string, string, error)

func ListResponseReplayItems added in v1.1.77 

func ListResponseReplayItems(sessionDir, sessionID string, limit int) ([]json.RawMessage, error)

ListResponseReplayItems returns the ordered, sanitized native items from completed Responses turns. Callers can pass this sequence to a provider's native replay path instead of reconstructing prior assistant output from plain transcript text.

func LockRuntime added in v1.1.77 

func LockRuntime(sessionDir, sessionID string) func()

LockRuntime waits for the single-session lease. It is intentionally implemented as retrying TryLockRuntime so no database transaction remains open while an execution is running.

func LockSessionData added in v1.1.77 

func LockSessionData(sessionDir, sessionID string) func()

LockSessionData serializes short persistence mutations inside one process. Cross-process data consistency still comes from SQLite transactions.

func NextSessionRunAttempt added in v1.2.83 

func NextSessionRunAttempt(sessionDir, sessionID, intentID string) (int, error)

NextSessionRunAttempt returns the next ordered user-visible attempt for an ExecutionIntent. Callers must hold their Runtime admission lock while using the returned value and creating the Run, so two retry commands cannot select the same attempt number.

func OpenRootDB added in v1.1.61 

func OpenRootDB(sessionDir string) (*sql.DB, error)

OpenRootDB opens the shared sessions.db for a session root directory.

func OpenSharedDatabase added in v1.1.77 

func OpenSharedDatabase(path string) (*sql.DB, error)

OpenSharedDatabase returns the process-wide shared connection for path. Callers must not close the returned connection; CloseDatabases owns it.

func OpenStandaloneDB added in v1.1.73 

func OpenStandaloneDB(path string) (*sql.DB, error)

OpenStandaloneDB opens a configured, caller-owned SQLite connection.

func QueryDatabase added in v1.1.77 

func QueryDatabase(path string, fn func(*sql.DB) error) error

QueryDatabase runs a read operation through the process-wide shared connection for path. Callers must not retain db after fn returns.

func QueryRootDatabase added in v1.1.77 

func QueryRootDatabase(sessionDir string, fn func(*sql.DB) error) error

QueryRootDatabase runs a read operation against a session root's shared DB.

func ReclaimInterruptedToolExecution added in v1.1.78 

func ReclaimInterruptedToolExecution(sessionDir, executionKey string) (bool, error)

ReclaimInterruptedToolExecution atomically reopens a tool record after a process interruption. Read-only running/interrupted records are eligible automatically; side-effecting records require the explicit retry_requested state set by the confirmation API.

func ReopenSessionRun added in v1.2.83 

func ReopenSessionRun(sessionDir, runID, status, message string) error

ReopenSessionRun is an explicit recovery transition for a terminal run whose provider task can be resumed. Normal lifecycle callers must use UpdateSessionRunStatus, which rejects terminal-to-active regressions.

func RequestToolExecutionRecovery added in v1.1.78 

func RequestToolExecutionRecovery(sessionDir, sessionID, localTurnID string, providerCallIDs []string) (int64, error)

RequestToolExecutionRecovery marks selected interrupted tool calls for an explicit user-confirmed retry. It never changes completed records and does not itself execute any tool.

func RuntimeLeaseLost added in v1.2.92 

func RuntimeLeaseLost(sessionDir, sessionID string) <-chan struct{}

RuntimeLeaseLost returns the loss signal for the current process lease. It is intentionally read-only; callers use it to cancel work while every durable write still performs its own epoch/token fence check.

func SaveESMGuidance added in v1.2.83 

func SaveESMGuidance(sessionDir string, g ESMGuidance) error

func SaveExecutionIntent added in v1.2.83 

func SaveExecutionIntent(sessionDir string, intent ExecutionIntent) error

func SaveResponseItem added in v1.1.77 

func SaveResponseItem(sessionDir string, item ResponseItemArchive) error

func SaveResponseRun added in v1.1.77 

func SaveResponseRun(sessionDir string, run ResponseRun) error

func SaveResponseTurn added in v1.1.77 

func SaveResponseTurn(sessionDir string, turn ResponseTurn) error

func SaveSessionCapabilities added in v1.1.61 

func SaveSessionCapabilities(sessionDir string, caps SessionCapabilities) error

SaveSessionCapabilities persists per-session runtime capability state.

func SaveSessionCapabilityEvent added in v1.1.61 

func SaveSessionCapabilityEvent(sessionDir string, ev SessionCapabilityEvent) (string, error)

SaveSessionCapabilityEvent appends a capability transition event to the independent event table.

func SaveSessionRun added in v1.1.77 

func SaveSessionRun(sessionDir string, run SessionRun) error

func SaveSessionRunEvent added in v1.1.61 

func SaveSessionRunEvent(sessionDir string, ev SessionRunEvent) (string, error)

SaveSessionRunEvent appends a run lifecycle event to the independent run event table.

func SetChannelTools added in v1.1.77 

func SetChannelTools(sessionDir, sessionID string, tools []ChannelToolConfig) error

func SetSessionMetadata added in v1.2.83 

func SetSessionMetadata(sessionDir, sessionID string, metadata SessionMetadata) error

func StartConversationTurn added in v1.2.92 

func StartConversationTurn(sessionDir string, turn ConversationTurn) error

StartConversationTurn atomically writes turn/start and its boundary row.

func TransferBinding added in v1.1.77 

func TransferBinding(sessionDir, channelType, channelID, fromSessionID, toSessionID string) error

TransferBinding atomically moves a channel identity from one session to another.

func TryLockRuntime added in v1.1.77 

func TryLockRuntime(sessionDir, sessionID string) (func(), bool)

TryLockRuntime serializes one session across all processes. The process-local mutex remains a fast path, while the SQLite lease is the authority and is automatically renewed until release or lease loss.

func TryLockRuntimes added in v1.1.77 

func TryLockRuntimes(sessionDir string, sessionIDs []string) (func(), bool)

TryLockRuntimes acquires multiple session leases in sorted order. Different sessions remain independently concurrent; ordering only applies to an operation that explicitly spans more than one session.

func UnbindSession added in v1.1.77 

func UnbindSession(sessionDir, sessionID string) error

UnbindSession makes a channel-bound session local while retaining its history.

func UpdateSessionRunErrorInfo added in v1.2.83 

func UpdateSessionRunErrorInfo(sessionDir, runID string, info json.RawMessage) error

UpdateSessionRunErrorInfo stores the structured terminal/recovery error independently of the compatibility Error summary column.

func UpdateSessionRunProgress added in v1.2.83 

func UpdateSessionRunProgress(sessionDir, runID string, progress json.RawMessage) error

UpdateSessionRunProgress persists the latest non-terminal retry/recovery projection. Terminal callers should clear it with an empty object.

func UpdateSessionRunStatus added in v1.1.77 

func UpdateSessionRunStatus(sessionDir, runID, status, message string, finishedAt *time.Time) error

func UpdateSessionRunUsage added in v1.2.83 

func UpdateSessionRunUsage(sessionDir, runID string, usage, contextUsage json.RawMessage) error

UpdateSessionRunUsage persists token and context-window usage independently from terminalization so reconnects can inspect partial or recovered runs.

func UpdateToolExecutionRecord added in v1.1.77 

func UpdateToolExecutionRecord(sessionDir string, record ToolExecutionRecord) error

func WriteDatabase added in v1.1.77 

func WriteDatabase(ctx context.Context, path string, fn func(*sql.Tx) error) error

WriteDatabase runs a write operation in one transaction through the process-wide shared connection for path.

func WriteRootDatabase added in v1.1.77 

func WriteRootDatabase(ctx context.Context, sessionDir string, fn func(*sql.Tx) error) error

WriteRootDatabase runs a write transaction against a session root's shared DB.

Types

type AdditionalDirectoriesEntry added in v1.2.90 

type AdditionalDirectoriesEntry struct {
	EntryBase
	Directories []string `json:"directories"`
}

AdditionalDirectoriesEntry records the complete ordered directory set granted to a session. Replacements are replayable session entries.

type Binding added in v1.1.77 

type Binding struct {
	SessionID   string `json:"sessionId"`
	ChannelType string `json:"channelType"`
	ChannelID   string `json:"channelId"`
}

Binding describes a current external channel binding.

func FindBinding added in v1.1.77 

func FindBinding(sessionDir, channelType, channelID string) (*Binding, error)

func FindBindingBySessionID added in v1.1.77 

func FindBindingBySessionID(sessionDir, sessionID string) (*Binding, error)

FindBindingBySessionID returns the current external binding for a session.

func ListBindings added in v1.1.77 

func ListBindings(sessionDir string) ([]Binding, error)

type BranchSummaryEntry 

type BranchSummaryEntry struct {
	EntryBase
	Summary string `json:"summary"`
	FromID  string `json:"fromId"`
}

BranchSummaryEntry records a branch switch summary.

type ChannelToolConfig added in v1.1.77 

type ChannelToolConfig struct {
	ToolName string `json:"toolName"`
	Enabled  bool   `json:"enabled"`
}

ChannelToolConfig describes one persisted tool selection for a channel session.

func ListChannelTools added in v1.1.77 

func ListChannelTools(sessionDir, sessionID string) ([]ChannelToolConfig, error)

type CompactionEntry 

type CompactionEntry struct {
	EntryBase
	Summary              string `json:"summary"`
	FirstKeptEntry       string `json:"firstKeptEntryId"`
	TokensBefore         int    `json:"tokensBefore"`
	SummaryVersion       int    `json:"summaryVersion,omitempty"`
	PreviousCompactionID string `json:"previousCompactionId,omitempty"`
	LastSummarizedEntry  string `json:"lastSummarizedEntryId,omitempty"`
}

CompactionEntry records a context compaction.

type ConversationTurn added in v1.2.92 

type ConversationTurn struct {
	ID        string
	SessionID string
	IntentID  string
	RunID     string
	Attempt   int
	Kind      string
	Status    string
	StartSeq  int64
	EndSeq    *int64
	StartedAt time.Time
	EndedAt   *time.Time
}

ConversationTurn is the durable boundary index used by Session fork resolution. It is intentionally separate from SessionRun because a Run may execute tools or maintenance work without producing a conversation turn.

func ListConversationTurns added in v1.2.92 

func ListConversationTurns(sessionDir, sessionID string) ([]ConversationTurn, error)

ListConversationTurns returns boundary rows in transcript order.

type ESMGuidance added in v1.2.83 

type ESMGuidance struct {
	ID               string     `json:"id"`
	SessionID        string     `json:"sessionId"`
	ObjectiveVersion string     `json:"objectiveVersion,omitempty"`
	Guidance         string     `json:"guidance"`
	Status           string     `json:"status"`
	CreatedAt        time.Time  `json:"createdAt"`
	ConsumedAt       *time.Time `json:"consumedAt,omitempty"`
}

func ListESMGuidance added in v1.2.83 

func ListESMGuidance(sessionDir, sessionID, status string, limit int) ([]ESMGuidance, error)

type EntryBase 

type EntryBase struct {
	Type      EntryType `json:"type"`
	ID        string    `json:"id"`
	ParentID  *string   `json:"parentId"`
	Timestamp time.Time `json:"timestamp"`
}

EntryBase contains common fields for all session entries.

type EntryType 

type EntryType string

EntryType identifies the type of a session entry. 

const (
	EntrySession               EntryType = "session"
	EntryMessage               EntryType = "message"
	EntryModelChange           EntryType = "model_change"
	EntryModeChange            EntryType = "mode_change"
	EntryThinkingChange        EntryType = "thinking_level_change"
	EntryAdditionalDirectories EntryType = "additional_directories"
	EntryCompaction            EntryType = "compaction"
	EntryBranchSummary         EntryType = "branch_summary"
	EntryCustom                EntryType = "custom"
	EntryCustomMessage         EntryType = "custom_message"
	EntryLabel                 EntryType = "label"
	EntrySessionInfo           EntryType = "session_info"
	EntryTurnStart             EntryType = "turn_start"
	EntryTurnEnd               EntryType = "turn_end"
)

type ExecutionIntent added in v1.2.83 

type ExecutionIntent struct {
	ID                 string
	SessionID          string
	Source             string
	Model              string
	Mode               string
	WorkDir            string
	RequestFingerprint string
	Request            json.RawMessage
	Policy             json.RawMessage
	CreatedAt          time.Time
}

ExecutionIntent is the durable, adapter-neutral record of an accepted user request. Request and policy snapshots are opaque to session storage; the shared Runtime owns their interpretation.

func GetExecutionIntent added in v1.2.83 

func GetExecutionIntent(sessionDir, intentID string) (*ExecutionIntent, error)

type ForkKind added in v1.2.92 

type ForkKind string
const (
	ForkKindSession ForkKind = "session"
	ForkKindMessage ForkKind = "message"
	ForkKindUnknown ForkKind = ""
)

type ForkOptions added in v1.2.92 

type ForkOptions struct {
	SourceSessionID string
	AtSeq           *int64
	RequestID       string
	TitleMode       string
}

type ForkResult added in v1.2.92 

type ForkResult struct {
	SessionID       string   `json:"sessionId"`
	ParentSessionID string   `json:"parentSessionId"`
	ForkKind        ForkKind `json:"forkKind"`
	BoundarySeq     int64    `json:"boundarySeq"`
	SeedLength      int64    `json:"seedLength"`
}

func ForkSession added in v1.2.92 

func ForkSession(ctx context.Context, sessionDir string, options ForkOptions) (ForkResult, error)
type Header struct {
	Type            EntryType `json:"type"`
	Version         int       `json:"version"`
	ID              string    `json:"id"`
	Timestamp       time.Time `json:"timestamp"`
	Cwd             string    `json:"cwd"`
	ParentSession   string    `json:"parentSession,omitempty"`
	ChannelType     string    `json:"channelType,omitempty"`
	ChannelID       string    `json:"channelId,omitempty"`
	ForkBoundarySeq int64     `json:"forkBoundarySeq,omitempty"`
	SeedLength      int64     `json:"seedLength,omitempty"`
	ForkKind        string    `json:"forkKind,omitempty"`
}

Header is the first line of a session file.

type IdentityLocks added in v1.1.77 

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

IdentityLocks serializes operations for one external channel identity. It is shared by inbound dispatch and session lifecycle management.

func NewIdentityLocks added in v1.1.77 

func NewIdentityLocks() *IdentityLocks

func (*IdentityLocks) Lock added in v1.1.77 

func (s *IdentityLocks) Lock(channelType, channelID string) func()

type LabelEntry 

type LabelEntry struct {
	EntryBase
	TargetID string  `json:"targetId"`
	Label    *string `json:"label,omitempty"`
}

LabelEntry records a user-defined label on an entry.

type ListOption added in v1.1.77 

type ListOption func(*listOptions)

func WithLimit added in v1.1.77 

func WithLimit(limit int) ListOption

func WithMessagesOnly added in v1.2.83 

func WithMessagesOnly() ListOption

WithMessagesOnly limits session listings to sessions containing at least one persisted conversation message. This avoids loading transient empty sessions during history pagination.

func WithOffset added in v1.1.77 

func WithOffset(offset int) ListOption

func WithSearch added in v1.2.83 

func WithSearch(search string) ListOption

WithSearch filters sessions by ID, work directory, channel metadata, or persisted message/session-info content. It is intended for session listings.

type Manager 

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

Manager manages a single session's state and persistence.

func ContinueRecent 

func ContinueRecent(cwd, sessionDir string) (*Manager, error)

ContinueRecent continues the most recent session for a directory, or creates new.

func CreateBound added in v1.1.77 

func CreateBound(workDir, sessionDir, channelType, channelID string) (*Manager, error)

func New 

func New(cwd, sessionDir string) *Manager

New creates a new session manager for a new session.

func NewSubAgent added in v1.1.62 

func NewSubAgent(cwd, sessionDir string) *Manager

NewSubAgent creates a session manager whose records are stored separately from user-continuable sessions.

func Open 

func Open(path string) (*Manager, error)

Open opens an existing session file.

func OpenByID 

func OpenByID(cwd, sessionDir, sessionID string) (*Manager, error)

OpenByID opens the session for cwd whose session ID matches sessionID. Supports prefix matching — if sessionID matches multiple sessions, an error is returned.

func OpenByIDExact 

func OpenByIDExact(sessionDir, sessionID string) (*Manager, error)

OpenByIDExact opens a session by exact session ID regardless of cwd.

func OpenByPathOrID 

func OpenByPathOrID(cwd, sessionDir, value string) (*Manager, error)

OpenByPathOrID opens a session using either an explicit file path or a session ID for the supplied working directory.

func RotateBoundSession added in v1.1.77 

func RotateBoundSession(workDir, sessionDir, channelType, channelID, oldSessionID string) (*Manager, error)

RotateBoundSession atomically creates a new bound session and clears the old one.

func (*Manager) AppendAdditionalDirectories added in v1.2.90 

func (m *Manager) AppendAdditionalDirectories(directories []string) (string, error)

AppendAdditionalDirectories records a complete replacement of the session's additional directory roots.

func (*Manager) AppendCompaction 

func (m *Manager) AppendCompaction(summary, firstKeptEntryID string, tokensBefore int) (string, error)

AppendCompaction records a context compaction.

func (*Manager) AppendMessage 

func (m *Manager) AppendMessage(msg provider.Message) (string, error)

AppendMessage adds a message entry.

func (*Manager) AppendModeChange added in v1.2.90 

func (m *Manager) AppendModeChange(mode string) (string, error)

AppendModeChange records a session execution mode change.

func (*Manager) AppendModelChange 

func (m *Manager) AppendModelChange(providerName, modelID string) (string, error)

AppendModelChange records a model change.

func (*Manager) AppendSessionInfo 

func (m *Manager) AppendSessionInfo(name string) (string, error)

AppendSessionInfo records a session display name. It is retained for compatibility; new callers should use AppendSessionTitle with a source.

func (*Manager) AppendSessionTitle added in v1.2.83 

func (m *Manager) AppendSessionTitle(name, source string) (string, error)

AppendSessionTitle records a session display name and its origin.

func (*Manager) AppendThinkingLevelChange 

func (m *Manager) AppendThinkingLevelChange(level string) (string, error)

AppendThinkingLevelChange records a thinking level change.

func (*Manager) EndConversationTurn added in v1.2.92 

func (m *Manager) EndConversationTurn(turnID, status, stopReason string) error

EndConversationTurn closes the durable boundary used by Session fork resolution. It is safe for callers to report failed, cancelled and incomplete outcomes; all are terminal turn states.

func (*Manager) GetFile 

func (m *Manager) GetFile() string

GetFile returns the session file path.

func (*Manager) GetHeader 

func (m *Manager) GetHeader() *Header

GetHeader returns the session header.

func (*Manager) GetLatestAdditionalDirectories added in v1.2.90 

func (m *Manager) GetLatestAdditionalDirectories() (AdditionalDirectoriesEntry, bool)

GetLatestAdditionalDirectories returns the latest complete directory-root binding persisted in this session.

func (*Manager) GetLatestCompaction 

func (m *Manager) GetLatestCompaction() (CompactionEntry, bool)

GetLatestCompaction returns the newest compaction entry in the current session.

func (*Manager) GetLatestModeChange added in v1.2.90 

func (m *Manager) GetLatestModeChange() (ModeChangeEntry, bool)

GetLatestModeChange returns the newest session mode in the session.

func (*Manager) GetLatestModelChange added in v1.2.90 

func (m *Manager) GetLatestModelChange() (ModelChangeEntry, bool)

GetLatestModelChange returns the newest model binding in the session.

func (*Manager) GetLatestThinkingLevelChange added in v1.2.90 

func (m *Manager) GetLatestThinkingLevelChange() (ThinkingLevelChangeEntry, bool)

GetLatestThinkingLevelChange returns the newest thinking level in the session.

func (*Manager) GetLeafID 

func (m *Manager) GetLeafID() *string

GetLeafID returns the current leaf entry ID.

func (*Manager) GetMessages 

func (m *Manager) GetMessages() []provider.Message

GetMessages extracts all messages from the current branch.

func (*Manager) GetReplayState 

func (m *Manager) GetReplayState() ReplayState

GetReplayState returns the current branch after applying compaction entries.

func (*Manager) GetSessionDir added in v1.1.77 

func (m *Manager) GetSessionDir() string

GetSessionDir returns the root directory containing this manager's shared sessions database. Runtime extensions use it for auxiliary session tables.

func (*Manager) Init 

func (m *Manager) Init() error

Init initializes a new session with an auto-generated session ID. Must be called before appending entries.

func (*Manager) InitWithBinding added in v1.1.77 

func (m *Manager) InitWithBinding(channelType, channelID string) error

InitWithBinding initializes a new session with a channel binding.

func (*Manager) InitWithID 

func (m *Manager) InitWithID(id string) error

InitWithID initializes a new session using the provided session ID. If id is empty, a new random ID is generated.

func (*Manager) InitWithIDAndBinding added in v1.1.77 

func (m *Manager) InitWithIDAndBinding(id, channelType, channelID string) error

InitWithIDAndBinding initializes a session with a specific ID and channel binding.

func (*Manager) RecordUsage 

func (m *Manager) RecordUsage(provider, protocol, model string, inputTokens, outputTokens, totalTokens, durationMs int) error

RecordUsage records a single LLM request's token usage and timing.

func (*Manager) RecordUsageFromProviderUsage 

func (m *Manager) RecordUsageFromProviderUsage(provider, protocol, model string, usage *provider.Usage, durationMs int) error

RecordUsageFromProviderUsage records usage from a provider.Usage struct.

func (*Manager) Reload added in v1.1.77 

func (m *Manager) Reload() error

Reload refreshes a manager from the shared SQLite session database. Serve entry points may retain a Manager while another UI writes the same session; reload after acquiring the session runtime lock so the next append uses the current leaf instead of an old optimistic-lock parent.

func (*Manager) SetSessionBinding added in v1.1.77 

func (m *Manager) SetSessionBinding(channelType, channelID string) error

SetSessionBinding updates a Manager's in-memory header after a binding change.

func (*Manager) StartConversationTurn added in v1.2.92 

func (m *Manager) StartConversationTurn(turnID, intentID, runID string) error

StartConversationTurn opens the durable boundary used by Session fork resolution. It is intentionally optional on session.Store so transient and in-memory agents do not need a SQLite turn index.

type MemoryStore 

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

MemoryStore is an in-memory implementation of Store for testing. It does not persist data to disk.

func NewMemoryStore 

func NewMemoryStore() *MemoryStore

NewMemoryStore creates a new in-memory session store.

func (*MemoryStore) AppendAdditionalDirectories added in v1.2.90 

func (m *MemoryStore) AppendAdditionalDirectories(directories []string) (string, error)

func (*MemoryStore) AppendCompaction 

func (m *MemoryStore) AppendCompaction(summary, firstKeptEntryID string, tokensBefore int) (string, error)

func (*MemoryStore) AppendMessage 

func (m *MemoryStore) AppendMessage(msg provider.Message) (string, error)

func (*MemoryStore) AppendModeChange added in v1.2.90 

func (m *MemoryStore) AppendModeChange(mode string) (string, error)

func (*MemoryStore) AppendModelChange 

func (m *MemoryStore) AppendModelChange(providerName, modelID string) (string, error)

func (*MemoryStore) AppendSessionInfo 

func (m *MemoryStore) AppendSessionInfo(name string) (string, error)

func (*MemoryStore) AppendThinkingLevelChange 

func (m *MemoryStore) AppendThinkingLevelChange(level string) (string, error)

func (*MemoryStore) GetFile 

func (m *MemoryStore) GetFile() string

func (*MemoryStore) GetHeader 

func (m *MemoryStore) GetHeader() *Header

func (*MemoryStore) GetLatestAdditionalDirectories added in v1.2.90 

func (m *MemoryStore) GetLatestAdditionalDirectories() (AdditionalDirectoriesEntry, bool)

func (*MemoryStore) GetLatestCompaction 

func (m *MemoryStore) GetLatestCompaction() (CompactionEntry, bool)

func (*MemoryStore) GetLatestModeChange added in v1.2.90 

func (m *MemoryStore) GetLatestModeChange() (ModeChangeEntry, bool)

func (*MemoryStore) GetLatestModelChange added in v1.2.90 

func (m *MemoryStore) GetLatestModelChange() (ModelChangeEntry, bool)

func (*MemoryStore) GetLatestThinkingLevelChange added in v1.2.90 

func (m *MemoryStore) GetLatestThinkingLevelChange() (ThinkingLevelChangeEntry, bool)

func (*MemoryStore) GetLeafID 

func (m *MemoryStore) GetLeafID() *string

func (*MemoryStore) GetMessages 

func (m *MemoryStore) GetMessages() []provider.Message

func (*MemoryStore) GetReplayState 

func (m *MemoryStore) GetReplayState() ReplayState

func (*MemoryStore) Init 

func (m *MemoryStore) Init() error

func (*MemoryStore) InitWithID 

func (m *MemoryStore) InitWithID(id string) error

type MessageEntry 

type MessageEntry struct {
	EntryBase
	Message provider.Message `json:"message"`
}

MessageEntry contains a conversation message.

type ModeChangeEntry added in v1.2.90 

type ModeChangeEntry struct {
	EntryBase
	Mode string `json:"mode"`
}

ModeChangeEntry records a session execution mode change.

type ModelChangeEntry 

type ModelChangeEntry struct {
	EntryBase
	Provider string `json:"provider"`
	ModelID  string `json:"modelId"`
}

ModelChangeEntry records a model switch.

type Project added in v1.2.83 

type Project struct {
	ID        string    `json:"id"`
	Name      string    `json:"name"`
	CreatedAt time.Time `json:"createdAt"`
	UpdatedAt time.Time `json:"updatedAt"`
}

func CreateProject added in v1.2.83 

func CreateProject(sessionDir, name string) (Project, error)

func ListProjects added in v1.2.83 

func ListProjects(sessionDir string) ([]Project, error)

func RenameProject added in v1.2.83 

func RenameProject(sessionDir, id, name string) (Project, error)

type ReplayState 

type ReplayState struct {
	Messages []provider.Message
	EntryIDs []string
}

ReplayState is the reconstructed conversation state after applying compactions.

type ResponseItemArchive added in v1.1.77 

type ResponseItemArchive struct {
	ID            int64
	SessionID     string
	LocalTurnID   string
	ResponseID    string
	ItemID        string
	OutputIndex   int
	ItemType      string
	ItemStatus    string
	ItemKey       string
	SanitizedJSON json.RawMessage
	CreatedAt     time.Time
}

ResponseItemArchive stores one sanitized normalized item. Raw provider request/response bodies must not be passed here.

func ListResponseItems added in v1.1.77 

func ListResponseItems(sessionDir, sessionID, localTurnID string) ([]ResponseItemArchive, error)

type ResponseReplayTurn added in v1.1.77 

type ResponseReplayTurn struct {
	LocalTurnID string
	Items       []json.RawMessage
}

ResponseReplayTurn groups the native output items belonging to one local Responses turn. It lets callers place those items at the corresponding assistant position while rebuilding a complete local conversation.

func ListResponseReplayTurns added in v1.1.77 

func ListResponseReplayTurns(sessionDir, sessionID string, limit int) ([]ResponseReplayTurn, error)

ListResponseReplayTurns returns completed native output grouped by local turn, ordered by their original completion order.

type ResponseRun added in v1.1.77 

type ResponseRun struct {
	ID                int64     `json:"id"`
	SessionID         string    `json:"sessionId"`
	LocalRunID        string    `json:"localRunId"`
	LocalTurnID       string    `json:"localTurnId,omitempty"`
	MessageID         *int64    `json:"messageId,omitempty"`
	ResponseID        string    `json:"responseId,omitempty"`
	Provider          string    `json:"provider"`
	API               string    `json:"api"`
	State             string    `json:"state"`
	PollingURL        string    `json:"pollingUrl,omitempty"`
	LastEventSequence *int64    `json:"lastEventSequence,omitempty"`
	CancelRequested   bool      `json:"cancelRequested,omitempty"`
	CreatedAt         time.Time `json:"createdAt"`
	UpdatedAt         time.Time `json:"updatedAt"`
}

ResponseRun is the durable state for a Responses background run.

func GetResponseRun added in v1.1.77 

func GetResponseRun(sessionDir, sessionID, localRunID string) (*ResponseRun, error)

func ListResponseRuns added in v1.1.77 

func ListResponseRuns(sessionDir, sessionID string, limit int) ([]ResponseRun, error)

type ResponseSessionState added in v1.1.77 

type ResponseSessionState struct {
	SessionID          string
	StateMode          string
	PreviousResponseID string
	ConversationID     string
	Provider           string
	API                string
	Model              string
	Version            int64
	UpdatedAt          time.Time
}

ResponseSessionState is the compare-and-swap protected remote lineage for a single local session. Provider config supplies defaults; this record keeps concurrent sessions and concurrent turns from sharing mutable remote state.

func GetResponseSessionState added in v1.1.77 

func GetResponseSessionState(sessionDir, sessionID string) (*ResponseSessionState, error)

GetResponseSessionState returns the durable remote lineage for a local session. A missing record means the caller must use its configured default, normally replay mode.

type ResponseTurn added in v1.1.77 

type ResponseTurn struct {
	ID                 int64
	SessionID          string
	LocalTurnID        string
	MessageID          *int64
	RequestID          string
	ResponseID         string
	PreviousResponseID string
	ConversationID     string
	Provider           string
	API                string
	Model              string
	StateMode          string
	Status             string
	IncompleteReason   string
	RequestSummary     json.RawMessage
	ResponseSummary    json.RawMessage
	CreatedAt          time.Time
	CompletedAt        *time.Time
}

ResponseTurn is the durable lineage and lifecycle summary for one Responses API turn. It intentionally contains summaries, not a second transcript.

func GetResponseTurn added in v1.1.77 

func GetResponseTurn(sessionDir, sessionID, localTurnID string) (*ResponseTurn, error)

type SequencedMessage added in v1.1.61 

type SequencedMessage struct {
	Seq     int64
	EntryID string
	Message provider.Message
}

SequencedMessage is a persisted conversation message with its entries.seq cursor.

func ListSessionMessagesAfter added in v1.1.61 

func ListSessionMessagesAfter(sessionDir, sessionID string, afterSeq int64, limit int) ([]SequencedMessage, error)

ListSessionMessagesAfter returns persisted message rows after entries.seq.

func ListSessionMessagesBefore added in v1.1.77 

func ListSessionMessagesBefore(sessionDir, sessionID string, beforeSeq int64, limit int) ([]SequencedMessage, error)

ListSessionMessagesBefore returns messages with seq < beforeSeq, newest first limited to `limit`.

func ListSessionMessagesLatest added in v1.1.77 

func ListSessionMessagesLatest(sessionDir, sessionID string, limit int) ([]SequencedMessage, error)

ListSessionMessagesLatest returns the latest N message entries (highest seq first).

func ListSessionMessagesWithSeq added in v1.1.61 

func ListSessionMessagesWithSeq(sessionDir, sessionID string) ([]SequencedMessage, error)

ListSessionMessagesWithSeq returns the visible replay messages for a session, preserving each message row's entries.seq cursor.

type SequencedSessionCapabilityEvent added in v1.1.61 

type SequencedSessionCapabilityEvent struct {
	Seq   int64
	Event SessionCapabilityEvent
}

SequencedSessionCapabilityEvent is a capability event with its table cursor.

func ListSessionCapabilityEventsAfter added in v1.1.61 

func ListSessionCapabilityEventsAfter(sessionDir, sessionID string, afterSeq int64, limit int) ([]SequencedSessionCapabilityEvent, error)

ListSessionCapabilityEventsAfter returns capability events after session_capability_events.seq.

func ListSessionCapabilityEventsWithSeq added in v1.1.61 

func ListSessionCapabilityEventsWithSeq(sessionDir, sessionID string) ([]SequencedSessionCapabilityEvent, error)

ListSessionCapabilityEventsWithSeq returns capability events with their seq cursor.

type SequencedSessionRunEvent added in v1.1.61 

type SequencedSessionRunEvent struct {
	Seq   int64
	Event SessionRunEvent
}

SequencedSessionRunEvent is a run lifecycle event with its table cursor.

func ListSessionRunEventsAfter added in v1.1.61 

func ListSessionRunEventsAfter(sessionDir, sessionID string, afterSeq int64, limit int) ([]SequencedSessionRunEvent, error)

ListSessionRunEventsAfter returns run events after session_run_events.seq.

func ListSessionRunEventsWithSeq added in v1.1.61 

func ListSessionRunEventsWithSeq(sessionDir, sessionID string) ([]SequencedSessionRunEvent, error)

ListSessionRunEventsWithSeq returns run events with their session_run_events.seq cursor.

type SessionCapabilities added in v1.1.61 

type SessionCapabilities struct {
	SessionID    string
	Mode         string
	DisplayMode  string
	DelegateMode bool
	MultiAgent   bool
	Workflows    bool
	WebSearch    bool
	Browser      bool
	A2AMaster    bool
	UpdatedAt    time.Time
}

SessionCapabilities stores persisted per-session runtime capability state.

func LoadSessionCapabilities added in v1.1.61 

func LoadSessionCapabilities(sessionDir, sessionID string) (*SessionCapabilities, bool, error)

LoadSessionCapabilities loads persisted capabilities for a session.

type SessionCapabilityEvent added in v1.1.61 

type SessionCapabilityEvent struct {
	ID         string
	SessionID  string
	RunID      string
	EventType  string
	Source     string
	Actor      string
	Capability string
	OldValue   string
	NewValue   string
	Timestamp  time.Time
	Data       json.RawMessage
}

SessionCapabilityEvent records one capability state transition.

func ListSessionCapabilityEvents added in v1.1.61 

func ListSessionCapabilityEvents(sessionDir, sessionID string) ([]SessionCapabilityEvent, error)

ListSessionCapabilityEvents returns capability events for a session, ordered by insertion.

type SessionDetail 

type SessionDetail struct {
	SessionInfo
	ID           string
	MessageCount int
	Preview      string // first user message (truncated)
}

SessionDetail contains detailed metadata about a session for display.

func ListAllDetailed added in v1.1.61 

func ListAllDetailed(sessionDir string, opts ...ListOption) ([]SessionDetail, error)

ListAllDetailed lists sessions with details across all working directories.

func ListForDirDetailed 

func ListForDirDetailed(cwd, sessionDir string) ([]SessionDetail, error)

ListForDirDetailed lists sessions with details (ID, message count, preview).

type SessionInfo 

type SessionInfo struct {
	Path            string
	ModTime         time.Time
	Name            string
	Cwd             string
	ChannelType     string
	ChannelID       string
	ParentSession   string
	ForkBoundarySeq int64
	SeedLength      int64
	ForkKind        string
}

SessionInfo contains metadata about a session file.

func ListAll added in v1.1.61 

func ListAll(sessionDir string, opts ...ListOption) ([]SessionInfo, error)

ListAll lists session files across all working directories.

func ListForDir 

func ListForDir(cwd, sessionDir string) ([]SessionInfo, error)

ListForDir lists session files for a given working directory.

type SessionInfoEntry 

type SessionInfoEntry struct {
	EntryBase
	Name   string `json:"name"`
	Source string `json:"source,omitempty"` // "manual" or "auto"
}

SessionInfoEntry stores session metadata.

type SessionMetadata added in v1.2.83 

type SessionMetadata struct {
	ProjectID string `json:"projectId,omitempty"`
	Pinned    bool   `json:"pinned"`
}

func GetSessionMetadata added in v1.2.83 

func GetSessionMetadata(sessionDir, sessionID string) (SessionMetadata, error)

type SessionRun added in v1.1.77 

type SessionRun struct {
	ID           string
	SessionID    string
	IntentID     string
	RetryOf      string
	Attempt      int
	WorkDir      string
	Source       string
	Model        string
	Mode         string
	Status       string
	StartedAt    time.Time
	UpdatedAt    time.Time
	FinishedAt   *time.Time
	Error        string
	ErrorInfo    json.RawMessage
	Progress     json.RawMessage
	Usage        json.RawMessage
	ContextUsage json.RawMessage
}

SessionRun is the durable lifecycle record for one agent execution.

func GetActiveSessionRun added in v1.1.77 

func GetActiveSessionRun(sessionDir, sessionID string) (*SessionRun, error)

func GetSessionRun added in v1.1.77 

func GetSessionRun(sessionDir, runID string) (*SessionRun, error)

func LatestSessionRunForIntent added in v1.2.83 

func LatestSessionRunForIntent(sessionDir, sessionID, intentID string) (*SessionRun, error)

LatestSessionRunForIntent returns the highest-attempt Run in an immutable intent chain. Retry admission uses it to prevent two callers from retrying an older terminal attempt after a newer attempt already exists.

func ListOrphanedSessionRuns added in v1.1.77 

func ListOrphanedSessionRuns(sessionDir string) ([]SessionRun, error)

ListOrphanedSessionRuns returns all runs that are in a non-terminal state. This is used during server startup to recover runs that were active when the previous server instance stopped.

func ListSessionRuns added in v1.1.77 

func ListSessionRuns(sessionDir, sessionID string, limit int) ([]SessionRun, error)

type SessionRunEvent added in v1.1.61 

type SessionRunEvent struct {
	ID        string
	SessionID string
	RunID     string
	EventType string
	Source    string
	Status    string
	Model     string
	Mode      string
	Timestamp time.Time
	Data      json.RawMessage
}

SessionRunEvent records one lifecycle event for a single chat/run execution.

func ListSessionRunEvents added in v1.1.61 

func ListSessionRunEvents(sessionDir, sessionID string) ([]SessionRunEvent, error)

ListSessionRunEvents returns run events for a session, ordered by insertion.

type Store 

type Store interface {
	// Init initializes the session store, creating the underlying
	// database or storage if needed.
	Init() error

	// InitWithID initializes the session with a specific ID.
	// An empty id generates a new one.
	InitWithID(id string) error

	// AppendMessage persists a conversation message and returns its entry ID.
	AppendMessage(msg provider.Message) (string, error)

	// AppendCompaction records a context compaction event.
	AppendCompaction(summary, firstKeptEntryID string, tokensBefore int) (string, error)

	// AppendModelChange records a model switch.
	AppendModelChange(providerName, modelID string) (string, error)

	// AppendModeChange records a session execution mode change.
	AppendModeChange(mode string) (string, error)

	// AppendThinkingLevelChange records a thinking level change.
	AppendThinkingLevelChange(level string) (string, error)
	AppendAdditionalDirectories(directories []string) (string, error)

	// AppendSessionInfo records session metadata.
	AppendSessionInfo(name string) (string, error)

	// GetMessages returns all messages in the current branch,
	// with compaction summaries applied.
	GetMessages() []provider.Message

	// GetReplayState returns the full replay state including
	// messages and their entry IDs.
	GetReplayState() ReplayState

	// GetLeafID returns the current leaf entry ID, or nil if empty.
	GetLeafID() *string

	// GetLatestCompaction returns the most recent compaction entry,
	// or (zero, false) if none exists.
	GetLatestCompaction() (CompactionEntry, bool)

	// GetLatestModelChange returns the most recent persisted model binding.
	GetLatestModelChange() (ModelChangeEntry, bool)

	// GetLatestModeChange returns the most recent persisted session mode.
	GetLatestModeChange() (ModeChangeEntry, bool)

	// GetLatestThinkingLevelChange returns the most recent persisted thinking level.
	GetLatestThinkingLevelChange() (ThinkingLevelChangeEntry, bool)
	GetLatestAdditionalDirectories() (AdditionalDirectoriesEntry, bool)

	// GetFile returns the session file path (handle file for SQLite).
	GetFile() string

	// GetHeader returns the session header with metadata.
	GetHeader() *Header
}

Store is the interface for session persistence backends. Manager implements this interface using SQLite. Alternative backends (in-memory for testing, cloud storage, etc.) can implement Store to swap the persistence layer without changing agent or UI code.

type ThinkingLevelChangeEntry 

type ThinkingLevelChangeEntry struct {
	EntryBase
	ThinkingLevel string `json:"thinkingLevel"`
}

ThinkingLevelChangeEntry records a thinking level change.

type ToolExecutionRecord added in v1.1.77 

type ToolExecutionRecord struct {
	ID               int64
	SessionID        string
	LocalTurnID      string
	ExecutionKey     string
	Provider         string
	API              string
	ResponseID       string
	ProviderCallID   string
	ToolKind         string
	ToolName         string
	ArgsHash         string
	ExecutionState   string
	ResultSummary    json.RawMessage
	ProviderMetadata json.RawMessage
	SideEffecting    bool
	CreatedAt        time.Time
	CompletedAt      *time.Time
}

ToolExecutionRecord is the cross-protocol idempotency record for a tool invocation. ExecutionKey is local and remains the deduplication authority.

func ClaimToolExecutionRecord added in v1.1.77 

func ClaimToolExecutionRecord(sessionDir string, record ToolExecutionRecord) (*ToolExecutionRecord, bool, error)

ClaimToolExecutionRecord atomically claims an execution key. A false created result means another request already owns the key and its record must be consulted before executing a side effect.

type TurnEndEntry added in v1.2.92 

type TurnEndEntry struct {
	EntryBase
	TurnID     string `json:"turnId"`
	IntentID   string `json:"intentId,omitempty"`
	RunID      string `json:"runId,omitempty"`
	Status     string `json:"status"`
	StopReason string `json:"stopReason,omitempty"`
}

TurnEndEntry marks the durable terminal boundary of a logical conversation turn. It is persisted for fork resolution and recovery, not model replay.

type TurnStartEntry added in v1.2.92 

type TurnStartEntry struct {
	EntryBase
	TurnID   string `json:"turnId"`
	IntentID string `json:"intentId,omitempty"`
	RunID    string `json:"runId,omitempty"`
	Attempt  int    `json:"attempt,omitempty"`
}

TurnStartEntry marks the durable beginning of a logical conversation turn. It is persisted for boundary recovery but is excluded from provider replay.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.