session

package
v0.6.0 Latest Latest
Warning

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

Go to latest
Published: Nov 17, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package session persists interactive conversations so they can be resumed later from the CLI (/resume).

Storage is append-only JSON Lines: one session is one <id>.jsonl file under ~/.oni3/sessions, and every turn is written as its own line. User and assistant text, model reasoning, tool calls, ask_user exchanges and task-list snapshots are all recorded; nothing is ever rewritten, so an interrupted turn leaves the file intact.

Index

Constants

View Source
const (
	EventSession   = "session"   // header line: id, kind, agent, model, skill
	EventConfig    = "config"    // later agent/model/skill change
	EventUser      = "user"      // user turn
	EventAssistant = "assistant" // assistant turn
	EventReasoning = "reasoning" // model thinking (may precede a tool call or answer)
	EventTool      = "tool"      // tool call start/end
	EventQuestion  = "question"  // ask_user question (Content) and answer (Result)
	EventTodo      = "todo"      // full task list snapshot
)

Event types stored in a session file.

View Source
const (
	ToolStart = "start"
	ToolEnd   = "end"
	ToolError = "error"
)

Tool statuses for EventTool.

View Source
const (
	KindAgent = "agent"
	KindChat  = "chat"
)

Session kinds. KindChat is kept for reading sessions written by older versions that still had a standalone chat mode; new sessions are agents.

View Source
const (
	RoleUser      = "user"
	RoleAssistant = "assistant"
)

Turn roles used by the recordTurn helpers.

View Source
const (
	TodoStatusPending    = "pending"
	TodoStatusInProgress = "in_progress"
	TodoStatusCompleted  = "completed"
)

Task statuses persisted in todo events.

Variables

This section is empty.

Functions

func Dir

func Dir() string

Dir returns the session storage directory.

Types

type Event

type Event struct {
	Type      string     `json:"type"`
	Time      time.Time  `json:"time"`
	ID        string     `json:"id,omitempty"`
	Kind      string     `json:"kind,omitempty"`
	Agent     string     `json:"agent,omitempty"`
	Model     string     `json:"model,omitempty"`
	Skill     string     `json:"skill,omitempty"`
	Content   string     `json:"content,omitempty"`
	Name      string     `json:"name,omitempty"`
	Arguments string     `json:"arguments,omitempty"`
	Result    string     `json:"result,omitempty"`
	Status    string     `json:"status,omitempty"`
	Todos     []TodoItem `json:"todos,omitempty"`
}

Event is one line of a session file. Fields are used depending on Type.

type Session

type Session struct {
	ID      string
	Kind    string
	Agent   string
	Model   string
	Skill   string
	Created time.Time
	Updated time.Time
	// contains filtered or unexported fields
}

Session is a persisted, append-only conversation.

func Find

func Find(kind, prefix string) (*Session, error)

Find resolves a session by exact ID or unique ID prefix within a kind.

func List

func List(kind string, limit int) ([]*Session, error)

List returns sessions of the given kind (all kinds when kind is empty), newest first, capped at limit (<= 0 means no cap).

func Load

func Load(id string) (*Session, error)

Load reads one session by exact ID, replaying every JSON line.

func New

func New(kind, agent, model, skill string) *Session

New creates an empty session with a time-ordered, human-readable ID. The file is created lazily on the first append.

func (*Session) AddAssistant

func (s *Session) AddAssistant(text string) error

AddAssistant appends an assistant turn.

func (*Session) AddQuestion

func (s *Session) AddQuestion(question, answer string) error

AddQuestion records an ask_user question and the user's answer ("" when the user cancelled).

func (*Session) AddReasoning

func (s *Session) AddReasoning(text string) error

AddReasoning appends a model thinking block.

func (*Session) AddTodos

func (s *Session) AddTodos(items []TodoItem) error

AddTodos records a complete task-list snapshot.

func (*Session) AddToolEnd

func (s *Session) AddToolEnd(name, result string, failed bool) error

AddToolEnd appends the completion of a tool call. failed reports an error result, which is preserved as the event status.

func (*Session) AddToolStart

func (s *Session) AddToolStart(name, arguments string) error

AddToolStart appends the start of a tool call.

func (*Session) AddUser

func (s *Session) AddUser(text string) error

AddUser appends a user turn.

func (*Session) Append

func (s *Session) Append(ev Event) error

Append writes one event as a JSON line. The session header is emitted automatically before the first event.

func (*Session) Events

func (s *Session) Events() []Event

Events returns a copy of the recorded events.

func (*Session) LastUserMessage

func (s *Session) LastUserMessage() string

LastUserMessage returns the most recent user turn, or "".

func (*Session) SetConfig

func (s *Session) SetConfig(agent, model, skill string) error

SetConfig records an agent/model/skill change. Replaying the file keeps the values from the last config event.

func (*Session) Todos

func (s *Session) Todos() []TodoItem

Todos returns the most recent task-list snapshot, or nil.

func (*Session) TurnCount

func (s *Session) TurnCount() int

TurnCount returns the number of user + assistant turns.

type TodoItem

type TodoItem struct {
	Content string `json:"content"`
	Status  string `json:"status"`
}

TodoItem is one persisted task-list entry.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL