The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
package fxsession
import (
"encoding/json"
"errors"
"fmt"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/sessionfs"
"io"
"io/fs"
"os"
"path/filepath"
"sort"
"strings"
)
const (
// EventsFileName and ManifestFileName are fx's names for the two files in a session directory
// (src/core/session/session_log.zig).
EventsFileName = "events.jsonl"
ManifestFileName = "session.json"
// ManifestSchemaVersion is the session.json version this reader understands. A different
// version is not an error: the manifest is an optimization, and the log can be read whole
// without it. See Store.Read.
ManifestSchemaVersion = 3
// MaxManifestBytes bounds the manifest read. fx's own limit is smaller; this leaves room for
// growth while still refusing to read an arbitrarily large file that happens to sit at that
// path.
MaxManifestBytes = 1 << 20
)
// DefaultSessionsDir returns fx's session directory for the current user.
//
// fx resolves its profile from $HOME (falling back to %USERPROFILE% on Windows), which is what
// os.UserHomeDir reports on both, so Beacon looks where fx writes rather than where a Beacon
// convention would put it. Nothing here creates the directory: its absence is the answer to "is
// this machine running fx", and creating it would fabricate the evidence.
func DefaultSessionsDir() (string, error) {
home, err := os.UserHomeDir()
if err != nil {
return "", fmt.Errorf("resolve home directory: %w", err)
}
if strings.TrimSpace(home) == "" {
return "", errors.New("home directory is empty")
}
return filepath.Join(home, ".fx", "sessions"), nil
}
// Manifest is fx's session.json: a projection of the session's committed state.
//
// EventLogBytes is the field this reader exists for. It is the length of the durable, committed
// prefix of events.jsonl -- fx appends a frame, then advances this watermark, so the bytes past it
// are a write in flight. Reading to the watermark rather than to EOF is what keeps a sweep from
// decoding a half-written frame and counting it as corruption.
type Manifest struct {
SchemaVersion int `json:"schema_version"`
StorageFormat string `json:"storage_format"`
ID string `json:"id"`
LogGeneration string `json:"log_generation"`
CreatedAtMS int64 `json:"created_at_ms"`
UpdatedAtMS int64 `json:"updated_at_ms"`
OriginWorkspaceRoot string `json:"origin_workspace_root"`
WorkspaceRoot string `json:"workspace_root"`
ConversationLang string `json:"conversation_language"`
HistoryLen int `json:"history_len"`
TotalInputTokens int64 `json:"total_input_tokens"`
TotalOutputTokens int64 `json:"total_output_tokens"`
LastEventSeq uint64 `json:"last_event_seq"`
EventLogBytes int64 `json:"event_log_bytes"`
Preferences *Preferences `json:"preferences"`
}
// SessionRef is one fx session on disk: where it is and, when the manifest could be read, what it
// says. Manifest is nil when there is no readable manifest, which is normal for a session fx has
// only just created.
type SessionRef struct {
ID string
Dir string
EventsLog string
Manifest *Manifest
// ModTimeUnixMS is the events.jsonl modification time, used as the change signal when no
// manifest is available. It is a fallback, not the primary cursor: the collector's real
// idempotence comes from the per-session sequence cursor, not from a timestamp.
ModTimeUnixMS int64
// SizeBytes is the events.jsonl size on disk, including any uncommitted tail.
SizeBytes int64
}
// Store is a directory of fx sessions, normally ~/.fx/sessions.
type Store struct {
Dir string
}
// NewStore points at dir, or at fx's default location when dir is empty.
func NewStore(dir string) (*Store, error) {
if strings.TrimSpace(dir) != "" {
return &Store{Dir: dir}, nil
}
def, err := DefaultSessionsDir()
if err != nil {
return nil, err
}
return &Store{Dir: def}, nil
}
// Exists reports whether the sessions directory is present. A missing directory means fx has not
// run for this user, which every caller reports rather than treats as a failure.
func (s *Store) Exists() bool {
info, err := sessionfs.Stat(s.Dir)
return err == nil && info.IsDir()
}
// List returns every session directory that holds an events log, oldest change first.
//
// Ordering is by the session's own last-modified time so a sweep processes sessions in roughly the
// order they were used, which keeps the resulting Beacon log close to chronological even before
// per-event timestamps sort it.
//
// An unreadable session directory is skipped rather than failing the listing: fx creates the
// directory before the log, another user's session may not be readable, and neither is a reason to
// collect nothing from the sessions that are.
func (s *Store) List() ([]SessionRef, error) {
entries, err := sessionfs.ReadDir(s.Dir)
if err != nil {
if errors.Is(err, fs.ErrNotExist) {
return nil, nil
}
return nil, fmt.Errorf("read fx sessions directory: %w", err)
}
refs := make([]SessionRef, 0, len(entries))
for _, entry := range entries {
if !entry.IsDir() {
continue
}
id := entry.Name()
if err := ValidateSessionID(id); err != nil {
continue
}
dir := filepath.Join(s.Dir, id)
logPath := filepath.Join(dir, EventsFileName)
info, err := sessionfs.Stat(logPath)
if err != nil || info.IsDir() {
continue
}
ref := SessionRef{
ID: id,
Dir: dir,
EventsLog: logPath,
ModTimeUnixMS: info.ModTime().UnixMilli(),
SizeBytes: info.Size(),
}
if manifest, err := ReadManifest(filepath.Join(dir, ManifestFileName)); err == nil {
ref.Manifest = manifest
}
refs = append(refs, ref)
}
sort.SliceStable(refs, func(i, j int) bool {
if refs[i].ModTimeUnixMS != refs[j].ModTimeUnixMS {
return refs[i].ModTimeUnixMS < refs[j].ModTimeUnixMS
}
return refs[i].ID < refs[j].ID
})
return refs, nil
}
// ValidateSessionID applies fx's own rule for a session id: non-empty, at most 255 bytes,
// alphanumerics plus `.`, `_` and `-`, and never "." or "..".
//
// Beacon re-applies it because the id is a path segment and reaches this code from a directory
// listing and from a state file that has been on disk between runs. A session id is also written
// into every event, so a name carrying a separator would be both a traversal risk here and a
// misleading identifier downstream.
func ValidateSessionID(id string) error {
if id == "" || len(id) > 255 || id == "." || id == ".." {
return fmt.Errorf("invalid fx session id %q", id)
}
for i := 0; i < len(id); i++ {
c := id[i]
switch {
case c >= 'a' && c <= 'z', c >= 'A' && c <= 'Z', c >= '0' && c <= '9':
case c == '.' || c == '_' || c == '-':
default:
return fmt.Errorf("invalid fx session id %q", id)
}
}
return nil
}
// ReadManifest reads and validates a session.json.
//
// A manifest whose schema version or storage format this reader does not recognize is an error
// rather than a partially-trusted value: its fields are what bound the log read, and reading the
// log whole is a correct fallback while trusting a byte count from a format that moved is not.
func ReadManifest(path string) (*Manifest, error) {
info, err := sessionfs.Stat(path)
if err != nil {
return nil, err
}
if info.Size() > MaxManifestBytes {
return nil, fmt.Errorf("fx manifest %s is %d bytes, over the %d-byte limit", path, info.Size(), MaxManifestBytes)
}
data, err := sessionfs.ReadFile(path)
if err != nil {
return nil, err
}
var manifest Manifest
if err := json.Unmarshal(data, &manifest); err != nil {
return nil, fmt.Errorf("fx manifest %s: %w", path, err)
}
if manifest.SchemaVersion != ManifestSchemaVersion {
return nil, fmt.Errorf("fx manifest %s: unsupported schema version %d", path, manifest.SchemaVersion)
}
if manifest.EventLogBytes < 0 {
return nil, fmt.Errorf("fx manifest %s: negative event_log_bytes", path)
}
return &manifest, nil
}
// Read decodes a session's events log, stopping at the manifest's committed watermark when there is
// one.
//
// The watermark is clamped to the file's actual size rather than trusted outright. The manifest is
// written after the log, so a manifest from a later state than the log on disk -- a restored
// backup, a copied directory, a partial sync -- would otherwise make the decoder read past EOF and
// report the whole session as unreadable.
//
// Events are returned in log order. The caller filters by cursor; this function has no opinion
// about what has already been collected.
func (s *Store) Read(ref SessionRef) ([]Event, Stats, error) {
file, err := sessionfs.Open(ref.EventsLog)
if err != nil {
return nil, Stats{}, err
}
defer file.Close()
limit := int64(0)
if ref.Manifest != nil && ref.Manifest.EventLogBytes > 0 {
limit = ref.Manifest.EventLogBytes
if info, err := file.Stat(); err == nil && info.Size() < limit {
limit = info.Size()
}
}
decoder := NewDecoder(file, limit)
var events []Event
for {
event, err := decoder.Next()
if errors.Is(err, io.EOF) {
break
}
if err != nil {
return events, decoder.Stats(), err
}
events = append(events, *event)
}
return events, decoder.Stats(), nil
}