sessiontree

package
v0.11.4 Latest Latest
Warning

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

 Go to latest Published: Jul 18, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package sessiontree stores durable conversation journals.

Repo implementations own thread metadata, append-only entries, forks, leaf movement, and provider-visible context reconstruction. FileRepo and MemoryRepo are safe for concurrent use. Repos used by agentharness should implement TurnLeaseRepo so active-turn serialization is durable per ThreadID and shared across harness instances that use the same backend. Different ThreadIDs, including forked threads, may run concurrently.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrThreadNotFound           = errors.New("session tree thread not found")
	ErrEntryNotFound            = errors.New("session tree entry not found")
	ErrInvalidParent            = errors.New("session tree invalid parent")
	ErrActiveTurn               = errors.New("session tree thread already has an active turn")
	ErrThreadExists             = errors.New("session tree thread already exists")
	ErrForkDestinationConflict  = errors.New("session tree fork destination conflicts with operation marker")
	ErrAgentTodoVersionConflict = errors.New("session tree agent todo version conflict")
)

Functions

func BuildContext 

func BuildContext(path []Entry, opts ContextOptions) []session.Message

func RawForEntry 

func RawForEntry(entry Entry) string

func SortThreadsByCreatedAtDesc 

func SortThreadsByCreatedAtDesc(threads []ThreadMeta)

func StableHash 

func StableHash(value string) string

Types

type AgentTodoItem added in v0.11.0 

type AgentTodoItem struct {
	ID      string          `json:"id"`
	Content string          `json:"content"`
	Status  AgentTodoStatus `json:"status"`
}

type AgentTodoState added in v0.11.0 

type AgentTodoState struct {
	ThreadID          string          `json:"thread_id"`
	Version           int64           `json:"version"`
	Items             []AgentTodoItem `json:"items"`
	UpdatedAt         time.Time       `json:"updated_at,omitempty"`
	UpdatedByTurnID   string          `json:"updated_by_turn_id,omitempty"`
	UpdatedByRunID    string          `json:"updated_by_run_id,omitempty"`
	UpdatedByToolCall string          `json:"updated_by_tool_call_id,omitempty"`
}

type AgentTodoStateRepo added in v0.11.0 

type AgentTodoStateRepo interface {
	ReadAgentTodoState(context.Context, string) (AgentTodoState, error)
	CompareAndSwapAgentTodoState(context.Context, AgentTodoState, int64) (AgentTodoState, error)
}

type AgentTodoStatus added in v0.11.0 

type AgentTodoStatus string
const (
	AgentTodoPending    AgentTodoStatus = "pending"
	AgentTodoInProgress AgentTodoStatus = "in_progress"
	AgentTodoCompleted  AgentTodoStatus = "completed"
)

type AppendCommittedError 

type AppendCommittedError struct {
	Err error
}

func (AppendCommittedError) Error 

func (e AppendCommittedError) Error() string

func (AppendCommittedError) Unwrap 

func (e AppendCommittedError) Unwrap() error

type AppendOptions 

type AppendOptions struct {
	ID       string
	ParentID string
	Now      time.Time
}

type ContextOptions 

type ContextOptions struct{}

type ContextProjection 

type ContextProjection struct {
	Messages []session.Message  `json:"messages"`
	Segments []ProjectedSegment `json:"segments,omitempty"`
}

func BuildContextProjection 

func BuildContextProjection(path []Entry, opts ContextProjectionOptions) ContextProjection

type ContextProjectionOptions 

type ContextProjectionOptions struct {
	Purpose ProjectionPurpose
}

type Entry 

type Entry struct {
	ID                      string              `json:"id"`
	ThreadID                string              `json:"thread_id"`
	ParentID                string              `json:"parent_id,omitempty"`
	Type                    EntryType           `json:"type"`
	TurnID                  string              `json:"turn_id,omitempty"`
	CreatedAt               time.Time           `json:"created_at"`
	Message                 session.Message     `json:"message,omitempty"`
	Raw                     string              `json:"raw,omitempty"`
	RawHash                 string              `json:"raw_hash,omitempty"`
	TurnStatus              TurnMarkerStatus    `json:"turn_status,omitempty"`
	Provider                string              `json:"provider,omitempty"`
	Model                   string              `json:"model,omitempty"`
	CompactionID            string              `json:"compaction_id,omitempty"`
	PreviousCompactionID    string              `json:"previous_compaction_id,omitempty"`
	CompactedThroughEntryID string              `json:"compacted_through_entry_id,omitempty"`
	SummarySchemaVersion    string              `json:"summary_schema_version,omitempty"`
	CompactionGeneration    int                 `json:"compaction_generation,omitempty"`
	CompactionWindowID      string              `json:"compaction_window_id,omitempty"`
	FirstKeptEntryID        string              `json:"first_kept_entry_id,omitempty"`
	KeptUserEntryIDs        []string            `json:"kept_user_entry_ids,omitempty"`
	Summary                 string              `json:"summary,omitempty"`
	CompactionTrigger       string              `json:"compaction_trigger,omitempty"`
	CompactionReason        string              `json:"compaction_reason,omitempty"`
	CompactionPhase         string              `json:"compaction_phase,omitempty"`
	CompactionOperationID   string              `json:"compaction_operation_id,omitempty"`
	CompactionRequestID     string              `json:"compaction_request_id,omitempty"`
	CompactionSource        string              `json:"compaction_source,omitempty"`
	TokensBefore            int64               `json:"tokens_before,omitempty"`
	TokensAfterEstimate     int64               `json:"tokens_after_estimate,omitempty"`
	ContextUsageBefore      contextpolicy.Usage `json:"context_usage_before,omitempty"`
	ContextUsageAfter       contextpolicy.Usage `json:"context_usage_after,omitempty"`
	Error                   string              `json:"error,omitempty"`
	Metadata                map[string]string   `json:"metadata,omitempty"`
}

func AppendActiveTools 

func AppendActiveTools(ctx context.Context, repo Repo, threadID string, metadata map[string]string) (Entry, error)

func AppendCompaction 

func AppendCompaction(ctx context.Context, repo Repo, threadID, turnID string, result compaction.Result) (Entry, error)

func AppendFailure 

func AppendFailure(ctx context.Context, repo Repo, threadID, turnID, message string) (Entry, error)

func AppendMessage 

func AppendMessage(ctx context.Context, repo Repo, threadID, turnID string, msg session.Message) (Entry, error)

func AppendMessageAt added in v0.3.56 

func AppendMessageAt(ctx context.Context, repo Repo, threadID, turnID string, msg session.Message, observedAt time.Time) (Entry, error)

func AppendTurnMarker 

func AppendTurnMarker(ctx context.Context, repo Repo, threadID, turnID string, status TurnMarkerStatus, metadata map[string]string) (Entry, error)

func AppendTurnMarkerWithID added in v0.11.0 

func AppendTurnMarkerWithID(ctx context.Context, repo Repo, threadID, turnID, entryID string, status TurnMarkerStatus, metadata map[string]string) (Entry, error)

func PrepareEntry 

func PrepareEntry(entry Entry) Entry

type EntryType 

type EntryType string
const (
	EntryThreadInfo       EntryType = "thread_info"
	EntryTurnMarker       EntryType = "turn_marker"
	EntryUserMessage      EntryType = "user_message"
	EntryAssistantMessage EntryType = "assistant_message"
	EntryToolCall         EntryType = "tool_call"
	EntryToolResult       EntryType = "tool_result"
	EntryModelChange      EntryType = "model_change"
	EntryActiveTools      EntryType = "active_tools_change"
	EntryCompaction       EntryType = "compaction"
	EntryBranchSummary    EntryType = "branch_summary"
	EntryRunFailure       EntryType = "run_failure"
	EntryCustom           EntryType = "custom"
)

type FileRepo 

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

func NewFileRepo 

func NewFileRepo(root string) *FileRepo

func (*FileRepo) AcquireTurnLease 

func (r *FileRepo) AcquireTurnLease(ctx context.Context, lease TurnLease) error

func (*FileRepo) ActiveTurnLease 

func (r *FileRepo) ActiveTurnLease(ctx context.Context, threadID string) (TurnLease, bool, error)

func (*FileRepo) Append 

func (r *FileRepo) Append(ctx context.Context, entry Entry, opts AppendOptions) (Entry, error)

func (*FileRepo) ClearExpiredTurnLease 

func (r *FileRepo) ClearExpiredTurnLease(ctx context.Context, threadID string, cutoff time.Time) (TurnLease, bool, error)

func (*FileRepo) CompareAndSwapAgentTodoState added in v0.11.0 

func (r *FileRepo) CompareAndSwapAgentTodoState(ctx context.Context, state AgentTodoState, expectedVersion int64) (AgentTodoState, error)

func (*FileRepo) CreateThread 

func (r *FileRepo) CreateThread(ctx context.Context, meta ThreadMeta) (ThreadMeta, error)

func (*FileRepo) DeleteThread 

func (r *FileRepo) DeleteThread(ctx context.Context, threadID string) error

func (*FileRepo) Entries 

func (r *FileRepo) Entries(ctx context.Context, threadID string) ([]Entry, error)

func (*FileRepo) Entry 

func (r *FileRepo) Entry(ctx context.Context, threadID, entryID string) (Entry, error)

func (*FileRepo) Fork 

func (r *FileRepo) Fork(ctx context.Context, opts ForkOptions) (ThreadMeta, error)

func (*FileRepo) ListThreads 

func (r *FileRepo) ListThreads(ctx context.Context, opts ListThreadsOptions) ([]ThreadMeta, error)

func (*FileRepo) MoveLeaf 

func (r *FileRepo) MoveLeaf(ctx context.Context, threadID, entryID string) error

func (*FileRepo) Path 

func (r *FileRepo) Path(ctx context.Context, threadID, leafID string) ([]Entry, error)

func (*FileRepo) PathPage added in v0.11.4 

func (r *FileRepo) PathPage(ctx context.Context, threadID, leafID, beforeEntryID string, limit int) (PathPage, error)

func (*FileRepo) ReadAgentTodoState added in v0.11.0 

func (r *FileRepo) ReadAgentTodoState(ctx context.Context, threadID string) (AgentTodoState, error)

func (*FileRepo) ReleaseTurnLease 

func (r *FileRepo) ReleaseTurnLease(ctx context.Context, lease TurnLease) error

func (*FileRepo) Thread 

func (r *FileRepo) Thread(ctx context.Context, threadID string) (ThreadMeta, error)

func (*FileRepo) UpdateThread 

func (r *FileRepo) UpdateThread(ctx context.Context, meta ThreadMeta) error

type ForkEntryIdentity added in v0.10.0 

type ForkEntryIdentity struct {
	SourceThreadID      string
	DestinationThreadID string
	TurnIDMap           map[string]string
	RunIDMap            map[string]string
}

type ForkOptions 

type ForkOptions struct {
	SourceThreadID  string
	EntryID         string
	EntryIDPinned   bool
	Position        ForkPosition
	NewThreadID     string
	OperationID     string
	OperationNodeID string
	Now             time.Time
	TurnIDMap       map[string]string
	RunIDMap        map[string]string
	RewriteEntry    func(Entry, ForkEntryIdentity) (Entry, error)
}

type ForkPosition 

type ForkPosition string
const (
	ForkAt     ForkPosition = "at"
	ForkBefore ForkPosition = "before"
)

type ListThreadsOptions 

type ListThreadsOptions struct {
	IncludeArchived bool
	Limit           int
	AfterCreatedAt  time.Time
	AfterID         string
}

type MemoryRepo 

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

func NewMemoryRepo 

func NewMemoryRepo() *MemoryRepo

func (*MemoryRepo) AcquireTurnLease 

func (r *MemoryRepo) AcquireTurnLease(_ context.Context, lease TurnLease) error

func (*MemoryRepo) ActiveTurnLease 

func (r *MemoryRepo) ActiveTurnLease(_ context.Context, threadID string) (TurnLease, bool, error)

func (*MemoryRepo) Append 

func (r *MemoryRepo) Append(_ context.Context, entry Entry, opts AppendOptions) (Entry, error)

func (*MemoryRepo) ClearExpiredTurnLease 

func (r *MemoryRepo) ClearExpiredTurnLease(_ context.Context, threadID string, cutoff time.Time) (TurnLease, bool, error)

func (*MemoryRepo) CompareAndSwapAgentTodoState added in v0.11.0 

func (r *MemoryRepo) CompareAndSwapAgentTodoState(_ context.Context, state AgentTodoState, expectedVersion int64) (AgentTodoState, error)

func (*MemoryRepo) CreateThread 

func (r *MemoryRepo) CreateThread(_ context.Context, meta ThreadMeta) (ThreadMeta, error)

func (*MemoryRepo) DeleteThread 

func (r *MemoryRepo) DeleteThread(_ context.Context, threadID string) error

func (*MemoryRepo) Entries 

func (r *MemoryRepo) Entries(_ context.Context, threadID string) ([]Entry, error)

func (*MemoryRepo) Entry 

func (r *MemoryRepo) Entry(_ context.Context, threadID, entryID string) (Entry, error)

func (*MemoryRepo) Fork 

func (r *MemoryRepo) Fork(ctx context.Context, opts ForkOptions) (ThreadMeta, error)

func (*MemoryRepo) ListThreads 

func (r *MemoryRepo) ListThreads(_ context.Context, opts ListThreadsOptions) ([]ThreadMeta, error)

func (*MemoryRepo) MoveLeaf 

func (r *MemoryRepo) MoveLeaf(_ context.Context, threadID, entryID string) error

func (*MemoryRepo) Path 

func (r *MemoryRepo) Path(_ context.Context, threadID, leafID string) ([]Entry, error)

func (*MemoryRepo) PathPage added in v0.11.4 

func (r *MemoryRepo) PathPage(_ context.Context, threadID, leafID, beforeEntryID string, limit int) (PathPage, error)

func (*MemoryRepo) ReadAgentTodoState added in v0.11.0 

func (r *MemoryRepo) ReadAgentTodoState(_ context.Context, threadID string) (AgentTodoState, error)

func (*MemoryRepo) ReleaseTurnLease 

func (r *MemoryRepo) ReleaseTurnLease(_ context.Context, lease TurnLease) error

func (*MemoryRepo) Thread 

func (r *MemoryRepo) Thread(_ context.Context, threadID string) (ThreadMeta, error)

func (*MemoryRepo) UpdateThread 

func (r *MemoryRepo) UpdateThread(_ context.Context, meta ThreadMeta) error

type PathPage added in v0.11.4 

type PathPage struct {
	Entries     []Entry
	NextEntryID string
	HasMore     bool
	// NewestOrdinal is the active-path ordinal of Entries[0]. Entries are
	// returned newest first, so later entries decrement this value by one.
	NewestOrdinal int64
}

type ProjectedSegment 

type ProjectedSegment struct {
	EntryID       string         `json:"entry_id,omitempty"`
	EntryType     EntryType      `json:"entry_type,omitempty"`
	MessageIndex  int            `json:"message_index"`
	Role          session.Role   `json:"role,omitempty"`
	ToolCallID    string         `json:"tool_call_id,omitempty"`
	ToolName      string         `json:"tool_name,omitempty"`
	TokenEstimate int64          `json:"token_estimate,omitempty"`
	ArtifactRefs  []artifact.Ref `json:"artifact_refs,omitempty"`
	UIPreview     string         `json:"ui_preview,omitempty"`
}

type ProjectionPurpose 

type ProjectionPurpose string
const (
	ProjectionProviderRequest ProjectionPurpose = "provider_request"
	ProjectionCompaction      ProjectionPurpose = "compaction"
	ProjectionTestUI          ProjectionPurpose = "test_ui"
)

type Repo 

type Repo interface {
	CreateThread(context.Context, ThreadMeta) (ThreadMeta, error)
	Thread(context.Context, string) (ThreadMeta, error)
	UpdateThread(context.Context, ThreadMeta) error
	DeleteThread(context.Context, string) error
	Append(context.Context, Entry, AppendOptions) (Entry, error)
	Entry(context.Context, string, string) (Entry, error)
	Entries(context.Context, string) ([]Entry, error)
	Path(context.Context, string, string) ([]Entry, error)
	PathPage(context.Context, string, string, string, int) (PathPage, error)
	MoveLeaf(context.Context, string, string) error
	Fork(context.Context, ForkOptions) (ThreadMeta, error)
}

type ThreadListRepo 

type ThreadListRepo interface {
	ListThreads(context.Context, ListThreadsOptions) ([]ThreadMeta, error)
}

type ThreadMeta 

type ThreadMeta struct {
	ID                  string            `json:"id"`
	LeafID              string            `json:"leaf_id,omitempty"`
	ParentThreadID      string            `json:"parent_thread_id,omitempty"`
	ParentTurnID        string            `json:"parent_turn_id,omitempty"`
	ForkedFromThreadID  string            `json:"forked_from_thread_id,omitempty"`
	ForkedFromEntryID   string            `json:"forked_from_entry_id,omitempty"`
	ForkOperationID     string            `json:"fork_operation_id,omitempty"`
	ForkOperationNodeID string            `json:"fork_operation_node_id,omitempty"`
	TaskName            string            `json:"task_name,omitempty"`
	TaskDescription     string            `json:"task_description,omitempty"`
	AgentPath           string            `json:"agent_path,omitempty"`
	HostProfileRef      string            `json:"host_profile_ref,omitempty"`
	ForkMode            string            `json:"fork_mode,omitempty"`
	Closed              bool              `json:"closed,omitempty"`
	Archived            bool              `json:"archived,omitempty"`
	Title               string            `json:"title,omitempty"`
	TitleStatus         ThreadTitleStatus `json:"title_status,omitempty"`
	TitleSource         ThreadTitleSource `json:"title_source,omitempty"`
	TitleUpdatedAt      time.Time         `json:"title_updated_at,omitempty"`
	TitleError          string            `json:"title_error,omitempty"`
	CreatedAt           time.Time         `json:"created_at"`
	UpdatedAt           time.Time         `json:"updated_at"`
	Status              string            `json:"status,omitempty"`
	LastViewedAt        time.Time         `json:"last_viewed_at,omitempty"`
}

func ApplyThreadListOptions 

func ApplyThreadListOptions(threads []ThreadMeta, opts ListThreadsOptions) []ThreadMeta

func ListThreads 

func ListThreads(ctx context.Context, repo Repo, opts ListThreadsOptions) ([]ThreadMeta, error)

type ThreadTitleSource 

type ThreadTitleSource string
const (
	ThreadTitleSourceProvider ThreadTitleSource = "provider"
	ThreadTitleSourceHost     ThreadTitleSource = "host"
)

type ThreadTitleStatus 

type ThreadTitleStatus string
const (
	ThreadTitleReady  ThreadTitleStatus = "ready"
	ThreadTitleFailed ThreadTitleStatus = "failed"
)

type TurnLease 

type TurnLease struct {
	ThreadID  string    `json:"thread_id"`
	TurnID    string    `json:"turn_id"`
	OwnerID   string    `json:"owner_id"`
	CreatedAt time.Time `json:"created_at"`
}

type TurnLeaseRepo 

type TurnLeaseRepo interface {
	AcquireTurnLease(context.Context, TurnLease) error
	ReleaseTurnLease(context.Context, TurnLease) error
	ActiveTurnLease(context.Context, string) (TurnLease, bool, error)
	ClearExpiredTurnLease(context.Context, string, time.Time) (TurnLease, bool, error)
}

type TurnMarkerStatus 

type TurnMarkerStatus string
const (
	TurnStarted   TurnMarkerStatus = "started"
	TurnSavePoint TurnMarkerStatus = "save_point"
	TurnCompleted TurnMarkerStatus = "completed"
	TurnWaiting   TurnMarkerStatus = "waiting"
	TurnFailed    TurnMarkerStatus = "failed"
	TurnAborted   TurnMarkerStatus = "aborted"
)

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.