session

package
v0.31.131 Latest Latest
Warning

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

 Go to latest Published: May 3, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	DefaultKeepRecentMessages = 20
	MinKeepRecentMessages     = 5
	MaxKeepRecentMessages     = 200
	DefaultKeepRecentTokens   = 12000
	MinKeepRecentTokens       = 1
	MaxKeepRecentTokens       = 64000
	DefaultKeepRecentFraction = 0.30
	MinKeepRecentFraction     = 0.05
	MaxKeepRecentFraction     = 0.90
)
View Source 
const (
	DefaultAutoResumeAfterMinutes = 30

	AutoResumeModeProceedWithAssumption      = "proceed_with_assumption"
	AutoResumeModeMoveToNextTask             = "move_to_next_task"
	AutoResumeModeRecordAssumptionAndProceed = "record_assumption_and_proceed"
)
View Source 
const (
	PlanStatusDrafting  = "drafting"
	PlanStatusProposed  = "proposed"
	PlanStatusExecuting = "executing"
	PlanStatusPaused    = "paused"
	PlanStatusCompleted = "completed"
	PlanStatusAborted   = "aborted"
)

Plan status constants — enumerate the states a plan can be in.

View Source 
const (
	ContractStatusDraft    = "draft"
	ContractStatusApproved = "approved"
)
View Source 
const (
	EvidenceTypeTestResult           = "test_result"
	EvidenceTypeImage                = "image"
	EvidenceTypeLogExcerpt           = "log_excerpt"
	EvidenceTypePRLink               = "pr_link"
	EvidenceTypeReleaseTag           = "release_tag"
	EvidenceTypeCommandOutputSummary = "command_output_summary"
)
View Source 
const (
	// TasksInjectionHeader marks task state that was deliberately reinserted
	// after context compression so later compactions can replace stale copies.
	TasksInjectionHeader = "## Active Plan (preserved across compression)"
)

Variables

This section is empty.

Functions

func AppendMessage 

func AppendMessage(path string, msg Message) error

AppendMessage appends a single message as one JSON line to the JSONL file at path.

func ArchiveSummary added in v0.20.0 

func ArchiveSummary(st SessionTasks) string

ArchiveSummary returns a human-readable summary of the plan and tasks for memory archival.

func BuildCompactionSummary 

func BuildCompactionSummary(messages []Message) string

func BuildCompactionSummaryWithOptions added in v0.10.2 

func BuildCompactionSummaryWithOptions(messages []Message, opts CompactionSummaryOptions) string

func EstimateMessageTokenCost added in v0.27.0 

func EstimateMessageTokenCost(msg Message) int

EstimateMessageTokenCost is the exported wrapper for single-message token estimation.

func EstimateTokens 

func EstimateTokens(messages []Message) int

func EvidenceTypeLabel added in v0.31.100 

func EvidenceTypeLabel(kind string) string

func FormatTasksForInjection added in v0.20.0 

func FormatTasksForInjection(st SessionTasks) string

FormatTasksForInjection renders active tasks for system prompt injection after context compression. Only includes pending and in_progress tasks.

func IsTasksInjectionMessage added in v0.31.16 

func IsTasksInjectionMessage(msg Message) bool

IsTasksInjectionMessage reports whether msg is a previously injected active plan block. Compaction replaces these blocks with fresh task state.

func NextEvidenceID added in v0.31.100 

func NextEvidenceID(tasks []Task) string

func NextTaskID added in v0.20.0 

func NextTaskID(tasks []Task) string

NextTaskID returns the next sequential task ID based on existing tasks.

func NormalizeAutoResumeModes added in v0.31.114 

func NormalizeAutoResumeModes(values []string) []string

func NowRFC3339 added in v0.20.0 

func NowRFC3339() string

NowRFC3339 returns current time in RFC3339 format.

func RewriteMessages 

func RewriteMessages(path string, messages []Message) error

RewriteMessages replaces the transcript contents with the provided messages.

func TaskSummary added in v0.20.0 

func TaskSummary(tasks []Task) map[string]int

TaskSummary returns a compact summary of task statuses.

func ValidEvidenceType added in v0.31.100 

func ValidEvidenceType(kind string) bool

func ValidPlanStatus added in v0.31.10 

func ValidPlanStatus(s string) bool

ValidPlanStatus reports whether s is a recognized plan status.

func ValidTaskStatus added in v0.20.0 

func ValidTaskStatus(status string) bool

ValidTaskStatus checks if a status string is valid.

Types

type CompactOptions 

type CompactOptions struct {
	BeforeRewrite       func(summary string, compactedCount int, originalCount int) error
	SummaryBuilder      func(messages []Message, previousContext string) (string, error)
	PostSummaryMessages []Message
	KeepRecentTokens    int
	KeepRecentFraction  float64
	SummaryInstructions string
	// PreloadedMessages supplies already-read messages to avoid a second ReadMessages
	// call on the same path. When set, ReadMessages is skipped, preventing a
	// reentrant-lock deadlock when the caller already holds the path lock.
	PreloadedMessages []Message
}

CompactOptions configures CompactTranscriptWithOptions.

KeepRecent strategies are tried in priority order — the first non-zero option wins, lower options are ignored:

  1. KeepRecentFraction (if > 0): retain the most recent X% of total transcript tokens (clamped to MinKeepRecentFraction..MaxKeepRecentFraction).
  2. KeepRecentTokens (if > 0): retain a specific token budget (clamped to MinKeepRecentTokens..MaxKeepRecentTokens).
  3. keepRecent positional argument: retain a specific message count (clamped to MinKeepRecentMessages..MaxKeepRecentMessages, default DefaultKeepRecentMessages = 20).

Setting both KeepRecentFraction and KeepRecentTokens is supported but the fraction wins — set only the strategy you want.

type CompactResult 

type CompactResult struct {
	Compacted      bool
	OriginalCount  int
	FinalCount     int
	CompactedCount int
	Summary        string
}

func CompactTranscript 

func CompactTranscript(path string, keepRecent int, now time.Time) (CompactResult, error)

func CompactTranscriptWithOptions 

func CompactTranscriptWithOptions(path string, keepRecent int, now time.Time, opts CompactOptions) (CompactResult, error)

type CompactionSummaryOptions added in v0.10.2 

type CompactionSummaryOptions struct {
	FocusInstructions string
	PreviousContext   string
}

type ForkOptions added in v0.31.105 

type ForkOptions struct {
	Title  string
	Reason string
}

ForkOptions controls how a child session is created from an existing transcript message.

type ForkPromotionCandidate added in v0.31.107 

type ForkPromotionCandidate struct {
	ID                  string    `json:"id"`
	SessionID           string    `json:"session_id"`
	ParentSessionID     string    `json:"parent_session_id"`
	RootSessionID       string    `json:"root_session_id,omitempty"`
	ForkedFromMessageID string    `json:"forked_from_message_id,omitempty"`
	ForkedFromIndex     *int      `json:"forked_from_index,omitempty"`
	MessageID           string    `json:"message_id"`
	MessageIndex        int       `json:"message_index"`
	Role                string    `json:"role"`
	Category            string    `json:"category"`
	Summary             string    `json:"summary"`
	CreatedAt           time.Time `json:"created_at"`
}

ForkPromotionCandidate is a reviewable insight from a forked session that can be queued into Memory Inbox for explicit user approval.

func DetectForkPromotionCandidates added in v0.31.107 

func DetectForkPromotionCandidates(sess Session, messages []Message, opts ForkPromotionOptions) []ForkPromotionCandidate

DetectForkPromotionCandidates extracts reusable post-fork insights without mutating any session transcript. It is intentionally deterministic so the UI can refresh and submit stable candidate IDs.

type ForkPromotionOptions added in v0.31.107 

type ForkPromotionOptions struct {
	Now             time.Time
	MaxCandidates   int
	MaxSummaryRunes int
}

ForkPromotionOptions controls deterministic candidate extraction from a fork.

type HistorySnapshot 

type HistorySnapshot struct {
	Messages       []Message
	Tokens         int
	CompactionUsed bool
}

HistorySnapshot captures the portion of transcript loaded into model context.

func LoadHistorySnapshot 

func LoadHistorySnapshot(path string, maxTokens int) (HistorySnapshot, error)

LoadHistorySnapshot reads transcript history and returns the loaded messages together with token and compaction-boundary metadata.

type Message 

type Message struct {
	ID          string    `json:"id,omitempty"`
	Role        string    `json:"role"`
	Content     string    `json:"content"`
	Timestamp   time.Time `json:"timestamp"`
	ToolName    string    `json:"tool_name,omitempty"`
	ToolCallID  string    `json:"tool_call_id,omitempty"`
	ToolArgs    string    `json:"tool_args,omitempty"`
	ToolIsError bool      `json:"tool_is_error,omitempty"`
}

Message represents a single chat message in a session transcript. Tool fields are optional (omitempty) for backward compatibility with existing transcripts.

func LoadHistory 

func LoadHistory(path string, maxTokens int) ([]Message, error)

LoadHistory reads messages from a JSONL file, returning only the most recent messages that fit within the given token budget. Tokens are estimated as len(content)/4. Messages are returned in chronological order (oldest first). Returns an empty slice if the file does not exist.

func ReadMessages 

func ReadMessages(path string) ([]Message, error)

ReadMessages reads all messages from a JSONL file. Returns an empty slice if the file does not exist or is empty.

type Plan added in v0.20.0 

type Plan struct {
	Goal        string `json:"goal"`
	Constraints string `json:"constraints,omitempty"`
	CreatedAt   string `json:"created_at"`
	Status      string `json:"status,omitempty"`
	UpdatedAt   string `json:"updated_at,omitempty"`
}

Plan represents a high-level goal for the current session. At most one plan is active per session; setting a new plan archives the previous one.

Status follows a small state machine: 

drafting ──plan_propose──► proposed ──plan_approve──► executing
   ▲                                                     │
   │                                                     │ plan_pause
   │                                                     ▼
   │                                                  paused
   │                                                     │
   │ user edit                       plan_resume         │
   └────────────────────                 ◄───────────────┘

executing ─(all tasks completed/cancelled)──► completed
any (except completed/aborted) ──plan_abort──► aborted

Empty Status (legacy plans saved before this field existed) is treated as "executing" on load so existing sessions keep their prior behavior.

type Session 

type Session struct {
	ID                  string                    `json:"id"`
	Title               string                    `json:"title"`
	Kind                string                    `json:"kind,omitempty"`
	Hidden              bool                      `json:"hidden,omitempty"`
	ParentSessionID     string                    `json:"parent_session_id,omitempty"`
	RootSessionID       string                    `json:"root_session_id,omitempty"`
	ForkedFromMessageID string                    `json:"forked_from_message_id,omitempty"`
	ForkedFromIndex     *int                      `json:"forked_from_index,omitempty"`
	ForkReason          string                    `json:"fork_reason,omitempty"`
	ToolConfig          *SessionToolConfig        `json:"tool_config,omitempty"`
	AutomationConsent   *SessionAutomationConsent `json:"automation_consent,omitempty"`
	StyleControl        *SessionStyleControl      `json:"style_control,omitempty"`
	LastCompactionMode  string                    `json:"last_compaction_mode,omitempty"`
	PromptOverride      string                    `json:"prompt_override,omitempty"`
	WorkDirs            []string                  `json:"work_dirs,omitempty"`
	CurrentDir          string                    `json:"current_dir,omitempty"`
	CreatedAt           time.Time                 `json:"created_at"`
	UpdatedAt           time.Time                 `json:"updated_at"`
}

type SessionAutomationConsent added in v0.31.108 

type SessionAutomationConsent struct {
	AutoResume             bool       `json:"auto_resume,omitempty"`
	AutoResumeEnabled      bool       `json:"auto_resume_enabled,omitempty"`
	AutoResumeAfterMinutes int        `json:"auto_resume_after_minutes,omitempty"`
	AllowedResumeModes     []string   `json:"allowed_resume_modes,omitempty"`
	GitMutations           bool       `json:"git_mutations,omitempty"`
	AutonomousMutations    bool       `json:"autonomous_mutations,omitempty"`
	UpdatedAt              *time.Time `json:"updated_at,omitempty"`
}

func (*SessionAutomationConsent) AllowsAutoResume added in v0.31.114 

func (c *SessionAutomationConsent) AllowsAutoResume() bool

func (*SessionAutomationConsent) AllowsAutonomousMutation added in v0.31.108 

func (c *SessionAutomationConsent) AllowsAutonomousMutation() bool

func (*SessionAutomationConsent) EffectiveAllowedResumeModes added in v0.31.114 

func (c *SessionAutomationConsent) EffectiveAllowedResumeModes() []string

func (*SessionAutomationConsent) EffectiveAutoResumeAfterMinutes added in v0.31.114 

func (c *SessionAutomationConsent) EffectiveAutoResumeAfterMinutes() int

type SessionStyleControl added in v0.31.120 

type SessionStyleControl struct {
	Directness *int       `json:"directness,omitempty"`
	Humor      *int       `json:"humor,omitempty"`
	Caution    *int       `json:"caution,omitempty"`
	Autonomy   *int       `json:"autonomy,omitempty"`
	UpdatedAt  *time.Time `json:"updated_at,omitempty"`
}

func NormalizeStyleControl added in v0.31.120 

func NormalizeStyleControl(style *SessionStyleControl) *SessionStyleControl

type SessionTasks added in v0.20.0 

type SessionTasks struct {
	Plan     *Plan         `json:"plan,omitempty"`
	Contract *TaskContract `json:"contract,omitempty"`
	Tasks    []Task        `json:"tasks"`
}

SessionTasks holds the current plan and its associated tasks for a session.

func (SessionTasks) MarshalJSON added in v0.23.0 

func (st SessionTasks) MarshalJSON() ([]byte, error)

MarshalJSON keeps the API contract stable by always emitting tasks as an array.

type SessionToolConfig added in v0.16.0 

type SessionToolConfig struct {
	ToolsEnabled     []string `json:"tools_enabled,omitempty"`
	ToolsCustom      bool     `json:"tools_custom,omitempty"`
	ToolsDisabled    []string `json:"tools_disabled,omitempty"`
	ToolsAllowGroups []string `json:"tools_allow_groups,omitempty"`
	ToolsDenyGroups  []string `json:"tools_deny_groups,omitempty"`
	SkillsEnabled    []string `json:"skills_enabled,omitempty"`
	SkillsCustom     bool     `json:"skills_custom,omitempty"`
	MCPEnabled       []string `json:"mcp_enabled,omitempty"`
}

SessionToolConfig holds per-session tool/skill/MCP configuration. nil slices mean "inherit all from system defaults".

type SessionWithPlanTasks added in v0.31.90 

type SessionWithPlanTasks struct {
	Session   Session        `json:"session"`
	Plan      *Plan          `json:"plan,omitempty"`
	Contract  *TaskContract  `json:"contract,omitempty"`
	Tasks     []Task         `json:"tasks"`
	Summary   map[string]int `json:"summary"`
	UpdatedAt time.Time      `json:"updated_at"`
}

type Store 

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

func NewStore 

func NewStore(dir string) *Store

func (*Store) Create 

func (s *Store) Create(title string) (Session, error)

func (*Store) CreateWithOptions 

func (s *Store) CreateWithOptions(title string, kind string, hidden bool) (Session, error)

func (*Store) Delete 

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

func (*Store) EnsureMain 

func (s *Store) EnsureMain() (Session, error)

func (*Store) EnsureWorker 

func (s *Store) EnsureWorker(projectID string) (Session, error)

func (*Store) ForkFromMessage added in v0.31.105 

func (s *Store) ForkFromMessage(parentID string, messageID string, opts ForkOptions) (Session, error)

ForkFromMessage creates a new visible session whose transcript contains the parent transcript prefix through the selected message.

func (*Store) Get 

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

func (*Store) GetTasks added in v0.20.0 

func (s *Store) GetTasks(sessionID string) (SessionTasks, error)

GetTasks reads the tasks file for a session. Returns empty SessionTasks if not found.

func (*Store) Latest 

func (s *Store) Latest() (Session, error)

func (*Store) LatestAll 

func (s *Store) LatestAll() (Session, error)

func (*Store) List 

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

func (*Store) ListAll 

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

func (*Store) ListSessionsWithPlans added in v0.31.90 

func (s *Store) ListSessionsWithPlans(includeHidden bool, activeOnly bool) ([]SessionWithPlanTasks, error)

func (*Store) SaveTasks added in v0.20.0 

func (s *Store) SaveTasks(sessionID string, tasks SessionTasks) error

SaveTasks writes the tasks file for a session.

func (*Store) SetAutomationConsent added in v0.31.108 

func (s *Store) SetAutomationConsent(id string, consent *SessionAutomationConsent) error

SetAutomationConsent updates the per-session automation consent policy.

func (*Store) SetCurrentDir added in v0.22.0 

func (s *Store) SetCurrentDir(id string, dir string) error

SetCurrentDir updates only the current working directory for a session.

func (*Store) SetLastCompactionMode added in v0.25.0 

func (s *Store) SetLastCompactionMode(id string, mode string) error

func (*Store) SetPromptOverride added in v0.16.0 

func (s *Store) SetPromptOverride(id string, override string) error

SetPromptOverride updates the per-session prompt override.

func (*Store) SetStyleControl added in v0.31.120 

func (s *Store) SetStyleControl(id string, style *SessionStyleControl) error

SetStyleControl updates the per-session behavioral style override.

func (*Store) SetTitle added in v0.15.0 

func (s *Store) SetTitle(id string, title string) error

SetTitle renames a session.

func (*Store) SetToolConfig added in v0.16.0 

func (s *Store) SetToolConfig(id string, config *SessionToolConfig) error

SetToolConfig updates the per-session tool configuration.

func (*Store) SetWorkDirs added in v0.22.0 

func (s *Store) SetWorkDirs(id string, dirs []string, currentDir string) error

SetWorkDirs updates the per-session working directories and current directory.

func (*Store) Touch 

func (s *Store) Touch(id string, updatedAt time.Time) error

func (*Store) TranscriptPath 

func (s *Store) TranscriptPath(id string) string

func (*Store) WorkspaceDir 

func (s *Store) WorkspaceDir() string

type Task added in v0.20.0 

type Task struct {
	ID          string         `json:"id"`
	Title       string         `json:"title"`
	Status      string         `json:"status"` // pending, in_progress, completed, cancelled
	Description string         `json:"description,omitempty"`
	Evidence    []TaskEvidence `json:"evidence,omitempty"`
}

Task represents a single work item linked to the session plan.

type TaskContract added in v0.31.98 

type TaskContract struct {
	Goal                 string   `json:"goal,omitempty"`
	Scope                string   `json:"scope,omitempty"`
	DoneCriteria         []string `json:"done_criteria,omitempty"`
	VerificationCommands []string `json:"verification_commands,omitempty"`
	Artifacts            []string `json:"artifacts,omitempty"`
	Status               string   `json:"status,omitempty"`
	CreatedAt            string   `json:"created_at,omitempty"`
	UpdatedAt            string   `json:"updated_at,omitempty"`
}

TaskContract makes the implicit work agreement explicit for a session plan. It is stored next to the active plan/tasks so reload, compaction, and archive flows can keep success criteria attached to the work rather than only in chat.

type TaskEvidence added in v0.31.100 

type TaskEvidence struct {
	ID        string `json:"id"`
	Type      string `json:"type"`
	Title     string `json:"title,omitempty"`
	Summary   string `json:"summary,omitempty"`
	URL       string `json:"url,omitempty"`
	Command   string `json:"command,omitempty"`
	Path      string `json:"path,omitempty"`
	Status    string `json:"status,omitempty"`
	CreatedAt string `json:"created_at,omitempty"`
}

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.