session

package
v1.6.0 Latest Latest
Warning

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

 Go to latest Published: Jun 30, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package session manages the lifecycle of agent sessions, including creation, persistence, checkpointing, and archival. Sessions are stored as JSON and Markdown files under ~/.m31a/sessions/.

Index

Constants

View Source 
const CurrentSchemaVersion = 1

CurrentSchemaVersion is the current session schema version. Increment when adding/removing fields that require migration.

Variables

This section is empty.

Functions

This section is empty.

Types

type Checkpoint 

type Checkpoint struct {
	Phase        types.WorkflowPhase `json:"phase"`
	Timestamp    time.Time           `json:"timestamp"`
	MessageCount int                 `json:"message_count"`
	TaskCount    int                 `json:"task_count"`
	Goal         string              `json:"goal,omitempty"`
	PlanVersion  int                 `json:"plan_version,omitempty"`
}

Checkpoint represents a point-in-time snapshot of workflow state, used by the /undo command to restore previous workflow phases.

type Manager 

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

Manager provides session operations. Sessions are stored project-locally in <workDir>/.m31a/ as flat files (one session per project). Global config (recent models, etc.) remains in <baseDir> (~/.m31a/).

func NewManager 

func NewManager(baseDir, workDir string, opts ManagerOpts) *Manager

NewManager creates a Manager with a global config directory and a project working directory. Session data is stored in <workDir>/.m31a/.

func (*Manager) AddRecentModel 

func (m *Manager) AddRecentModel(modelID string) error

AddRecentModel adds a model ID to the top of the recent list.

func (*Manager) BaseDir 

func (m *Manager) BaseDir() string

BaseDir returns the global config directory (~/.m31a/).

func (*Manager) Cleanup 

func (m *Manager) Cleanup(maxAge time.Duration) (int, error)

Cleanup is a no-op for project-local sessions (don't auto-delete project data).

func (*Manager) Coordinator added in v1.3.0 

func (m *Manager) Coordinator() *coordinator.Coordinator[string]

Coordinator returns the session run coordinator for managing concurrent session execution. Use Run/Interrupt/AwaitIdle to control session drains.

func (*Manager) DeleteSession 

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

DeleteSession removes the project-local session files without deleting the entire .m31a/ directory (which may contain backups, planning data, etc.).

func (*Manager) ExportSessionJSON 

func (m *Manager) ExportSessionJSON(id, path string) error

ExportSessionJSON exports the session's full data as a JSON file.

func (*Manager) ExportSessionMarkdown 

func (m *Manager) ExportSessionMarkdown(id, path string) error

ExportSessionMarkdown exports the session's messages as a markdown file.

func (*Manager) FilterSessions 

func (m *Manager) FilterSessions(query string) ([]SessionInfo, error)

FilterSessions returns sessions matching a query string.

func (*Manager) IsFavorite 

func (m *Manager) IsFavorite(modelID string) bool

IsFavorite checks whether a model ID is marked as a favorite.

func (*Manager) LatestCheckpoint 

func (m *Manager) LatestCheckpoint(sessionID string) (*Checkpoint, error)

LatestCheckpoint returns the most recently saved checkpoint. Returns ErrCheckpointNotFound if no checkpoints exist.

func (*Manager) ListSessions 

func (m *Manager) ListSessions() ([]SessionInfo, error)

ListSessions returns the current project session if one exists. With project-local sessions, there is at most one session per project.

func (*Manager) LoadCheckpoints 

func (m *Manager) LoadCheckpoints(sessionID string) ([]Checkpoint, error)

LoadCheckpoints reads all checkpoints from checkpoint.json for the given session. Returns an empty slice without error if the file does not exist. Prunes old checkpoints, keeping only the 2 most recent.

func (*Manager) LoadDemonstration 

func (m *Manager) LoadDemonstration(sessionID string) (string, error)

LoadDemonstration reads planning/DEMONSTRATION.md for the given session. Returns empty string without error if the file does not exist.

func (*Manager) LoadMessages 

func (m *Manager) LoadMessages(sessionID string) ([]types.Message, error)

LoadMessages reads messages.json from <workDir>/.m31a/.

func (*Manager) LoadPlan 

func (m *Manager) LoadPlan(sessionID string) (string, error)

LoadPlan reads planning/plan.md for the given session. Returns empty string without error if the file does not exist.

func (*Manager) LoadProject 

func (m *Manager) LoadProject(sessionID string) (*types.ProjectState, error)

LoadProject reads and parses planning/PROJECT.md for the given session. Returns nil without error if the file does not exist (graceful degradation).

func (*Manager) LoadRecentModels 

func (m *Manager) LoadRecentModels() (*RecentModelsData, error)

LoadRecentModels reads the recent models file from ~/.m31a/.

func (*Manager) LoadSession 

func (m *Manager) LoadSession(id string) (*Session, error)

LoadSession reads the project-local session from <workDir>/.m31a/session.json. The id parameter is accepted for API compatibility but ignored — the project directory contains at most one session.

func (*Manager) LoadSessionSummary added in v1.5.0 

func (m *Manager) LoadSessionSummary(sessionID string) (string, error)

LoadSessionSummary reads planning/SUMMARY.md for the given session. Returns empty string without error if the file does not exist.

func (*Manager) LoadState 

func (m *Manager) LoadState(sessionID string) (phase types.WorkflowPhase, progress, lastAction string, timestamp time.Time, err error)

LoadState reads and parses planning/STATE.md for the given session. Returns empty/default values without error if the file does not exist.

func (*Manager) LoadTasks 

func (m *Manager) LoadTasks(sessionID string) ([]types.Task, error)

LoadTasks reads and parses planning/TASKS.md for the given session. Returns an empty slice without error if the file does not exist.

func (*Manager) LoadWorkflowState 

func (m *Manager) LoadWorkflowState(id string) (goal string, phase types.WorkflowPhase, questions []string, err error)

LoadWorkflowState reads the persisted workflow state from session.json.

func (*Manager) NewSession 

func (m *Manager) NewSession(model, provider string) (*Session, error)

NewSession creates a new session in <workDir>/.m31a/. If a session already exists, the existing session.json is backed up to session.json.bak.

func (*Manager) RenameSession 

func (m *Manager) RenameSession(id, label string) error

RenameSession updates the session's label.

func (*Manager) SaveCheckpoint 

func (m *Manager) SaveCheckpoint(sessionID string, cp Checkpoint) error

SaveCheckpoint appends a checkpoint to checkpoint.json for the given session. If more than 2 checkpoints exist, the oldest are trimmed (only last 2 retained). Writes are atomic (temp + rename) per M-20.

func (*Manager) SaveDemonstration 

func (m *Manager) SaveDemonstration(sessionID string, markdown string) error

SaveDemonstration writes the demonstration markdown to planning/DEMONSTRATION.md.

func (*Manager) SaveMessages 

func (m *Manager) SaveMessages(sessionID string, messages []types.Message) error

SaveMessages writes messages.json to <workDir>/.m31a/.

func (*Manager) SavePlan 

func (m *Manager) SavePlan(sessionID string, version int, markdown string) error

SavePlan writes the plan markdown to planning/plan.md and a versioned copy to planning/plan_v{version}.md for refinement history.

func (*Manager) SaveProject 

func (m *Manager) SaveProject(sessionID string, project *types.ProjectState) error

SaveProject writes ProjectState to planning/PROJECT.md for the given session.

func (*Manager) SaveRecentModels 

func (m *Manager) SaveRecentModels(data *RecentModelsData) error

SaveRecentModels writes the recent models data to ~/.m31a/.

func (*Manager) SaveSession 

func (m *Manager) SaveSession(s *Session) error

SaveSession writes session.json and messages.json to <workDir>/.m31a/.

func (*Manager) SaveSessionSummary added in v1.5.0 

func (m *Manager) SaveSessionSummary(sessionID string, markdown string) error

SaveSessionSummary writes the session summary markdown to planning/SUMMARY.md.

func (*Manager) SaveState 

func (m *Manager) SaveState(sessionID string, phase types.WorkflowPhase, progress, lastAction string) error

SaveState writes workflow state to planning/STATE.md for the given session.

func (*Manager) SaveTasks 

func (m *Manager) SaveTasks(sessionID string, tasks []types.Task) error

SaveTasks writes a slice of Tasks to planning/TASKS.md as a markdown table.

func (*Manager) SaveTasksCheckbox 

func (m *Manager) SaveTasksCheckbox(sessionID string, tasks []types.Task) error

SaveTasksCheckbox writes a checkbox-style task list grouped by category to planning/tasks.md. Tasks are grouped by their Category field; tasks without a category go under "General".

func (*Manager) ToggleFavorite 

func (m *Manager) ToggleFavorite(modelID string) error

ToggleFavorite toggles the favorite status for a model ID.

func (*Manager) UpdateWorkflowState 

func (m *Manager) UpdateWorkflowState(id, goal string, phase types.WorkflowPhase, questions []string) error

UpdateWorkflowState persists the workflow state to session.json.

func (*Manager) WorkDir 

func (m *Manager) WorkDir() string

WorkDir returns the project root directory.

type ManagerOpts 

type ManagerOpts struct {
	SessionIDBytes  int           // Number of random bytes (4 = 8 hex chars). 0 = default.
	MaxRecentModels int           // Max recent models. 0 = default (10).
	SessionCacheTTL time.Duration // TTL for session list cache. 0 = default (2s).
}

ManagerOpts holds optional settings for the Manager.

type RecentModelsData 

type RecentModelsData struct {
	Recent    []string        `json:"recent"`
	Favorites map[string]bool `json:"favorites"`
}

RecentModelsData stores the recent model list and favorites.

type Session 

type Session struct {
	types.Session
	SchemaVersion int                 `json:"schema_version"`
	Messages      []types.Message     `json:"messages"`
	Tasks         []types.Task        `json:"tasks"`
	Project       *types.ProjectState `json:"project"`

	// ResumedAt records the time of the most recent resume. Nil for
	// never-resumed sessions. Updated on every Manager.LoadSession call.
	ResumedAt *time.Time `json:"resumed_at,omitempty"`

	// Workflow state (D-06 fix) — persisted to session.json so closing
	// the app mid-workflow doesn't abandon progress.
	WorkflowGoal     string   `json:"workflow_goal,omitempty"`
	DiscussQuestions []string `json:"discuss_questions,omitempty"`
}

Session wraps types.Session with additional runtime state fields.

func NewSession 

func NewSession(id, model, provider string) *Session

NewSession creates a new Session with default values.

func (*Session) SetPhase 

func (s *Session) SetPhase(phase types.WorkflowPhase)

SetPhase updates the workflow phase on the session.

func (*Session) SetWorkflowState 

func (s *Session) SetWorkflowState(goal string, phase types.WorkflowPhase, questions []string)

SetWorkflowState records the workflow's current goal, phase, and pending discuss questions. The TUI calls this on every phase transition via Manager.UpdateWorkflowState.

func (*Session) WorkflowState 

func (s *Session) WorkflowState() (goal string, phase types.WorkflowPhase, questions []string)

WorkflowState returns the persisted workflow state. Zero values for the goal and questions, and PhaseIdle for the phase, mean no workflow is in progress.

type SessionInfo 

type SessionInfo struct {
	ID            string              `json:"id"`
	ParentID      string              `json:"parent_id,omitempty"`
	ChildrenIDs   []string            `json:"children_ids,omitempty"`
	Label         string              `json:"label,omitempty"`
	Model         string              `json:"model"`
	Provider      string              `json:"provider"`
	StartedAt     time.Time           `json:"started_at"`
	LastModified  time.Time           `json:"last_modified"`
	MessageCount  int                 `json:"message_count"`
	Corrupted     bool                `json:"corrupted"`
	WorkflowPhase types.WorkflowPhase `json:"workflow_phase,omitempty"`
}

SessionInfo holds display metadata for session listings.

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.