sessiontree

package
v0.3.9 Latest Latest
Warning

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

 Go to latest Published: Jun 14, 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")
)

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 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"`
	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 AppendTurnMarker 

func AppendTurnMarker(ctx context.Context, repo Repo, threadID, turnID 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) 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) 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 ForkOptions 

type ForkOptions struct {
	SourceThreadID string
	EntryID        string
	Position       ForkPosition
	NewThreadID    string
	Now            time.Time
}

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) 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) 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 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)
	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"`
	ForkedFromThreadID string            `json:"forked_from_thread_id,omitempty"`
	ForkedFromEntryID  string            `json:"forked_from_entry_id,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.