Package com.tnsai.session

Class FileSessionStore

java.lang.Object
com.tnsai.session.FileSessionStore
All Implemented Interfaces:
SessionStore
Direct Known Subclasses:
SearchableFileSessionStore
public class FileSessionStore extends Object implements SessionStore
File-based implementation of SessionStore.

Stores sessions as JSON files organized by date: 

 basePath/
 ├── 2026-02-05/
 │   ├── session-abc123.json
 │   └── session-def456.json
 ├── 2026-02-04/
 │   └── session-ghi789.json
 └── index.json

Durability: session files and the index are written atomically (temp file + atomic move), so a crash mid-write cannot leave a half-written JSON file. Session files that fail to parse on load are quarantined (renamed to *.corrupt-<timestamp>) and treated as missing instead of failing the whole store.

The index is only persisted when the entry set actually changes (new, removed, or bucket-moved session), not on every save.

Concurrency: index writes are synchronized and atomic within a JVM, but the store assumes a single-writer contract per directory — two store instances (in the same or different JVMs) writing to the same base path may overwrite each other's index, since each keeps its own in-memory index cache.

Author:
TnsAI Team

  • Constructor Details

    • FileSessionStore

      public FileSessionStore(String basePath)
      Creates a file session store with no retention (existing behavior).
      Parameters:
      basePath - the base directory path

    • FileSessionStore

      public FileSessionStore(String basePath, long maxAgeDays)
      Creates a file session store with opt-in age-based retention.

      When maxAgeDays is positive, sessions older than the given number of days (based on session start time) are evicted — see evictExpired(). Retention runs once at construction and on explicit evictExpired() calls; it never runs during save(AgentSession). A value of 0 (or negative) disables retention entirely.

      Parameters:
      basePath - the base directory path
      maxAgeDays - maximum session age in days, 0 to disable retention

  • Method Details

    • save

      public void save(AgentSession session)
      Description copied from interface: SessionStore
      Saves a session.
      Specified by:
      save in interface SessionStore
      Parameters:
      session - the session to save

    • load

      public Optional<AgentSession> load(String sessionId)
      Description copied from interface: SessionStore
      Loads a session by ID.
      Specified by:
      load in interface SessionStore
      Parameters:
      sessionId - the session ID
      Returns:
      the session if found

    • delete

      public boolean delete(String sessionId)
      Description copied from interface: SessionStore
      Deletes a session.
      Specified by:
      delete in interface SessionStore
      Parameters:
      sessionId - the session ID
      Returns:
      true if deleted

    • listSessionIds

      public List<String> listSessionIds()
      Description copied from interface: SessionStore
      Lists all session IDs.
      Specified by:
      listSessionIds in interface SessionStore
      Returns:
      list of session IDs

    • findByDate

      public List<AgentSession> findByDate(LocalDate date)
      Description copied from interface: SessionStore
      Lists sessions for a specific date.
      Specified by:
      findByDate in interface SessionStore
      Parameters:
      date - the date
      Returns:
      list of sessions

    • findByDateRange

      public List<AgentSession> findByDateRange(LocalDate startDate, LocalDate endDate)
      Description copied from interface: SessionStore
      Lists sessions in a date range.
      Specified by:
      findByDateRange in interface SessionStore
      Parameters:
      startDate - start date (inclusive)
      endDate - end date (inclusive)
      Returns:
      list of sessions

    • findByAgent

      public List<AgentSession> findByAgent(String agentName)
      Description copied from interface: SessionStore
      Lists sessions for a specific agent.
      Specified by:
      findByAgent in interface SessionStore
      Parameters:
      agentName - the agent name
      Returns:
      list of sessions

    • findByProject

      public List<AgentSession> findByProject(String projectPath)
      Description copied from interface: SessionStore
      Lists sessions for a specific project.
      Specified by:
      findByProject in interface SessionStore
      Parameters:
      projectPath - the project path
      Returns:
      list of sessions

    • findByTag

      public List<AgentSession> findByTag(String tag)
      Description copied from interface: SessionStore
      Lists sessions with a specific tag.
      Specified by:
      findByTag in interface SessionStore
      Parameters:
      tag - the tag
      Returns:
      list of sessions

    • findByOutcome

      public List<AgentSession> findByOutcome(SessionOutcome outcome)
      Description copied from interface: SessionStore
      Lists sessions with a specific outcome.
      Specified by:
      findByOutcome in interface SessionStore
      Parameters:
      outcome - the outcome
      Returns:
      list of sessions

    • findRecent

      public List<AgentSession> findRecent(int limit)
      Description copied from interface: SessionStore
      Gets the most recent sessions.
      Specified by:
      findRecent in interface SessionStore
      Parameters:
      limit - maximum number to return
      Returns:
      list of sessions, newest first

    • count

      public int count()
      Description copied from interface: SessionStore
      Counts total sessions.
      Specified by:
      count in interface SessionStore
      Returns:
      session count

    • exists

      public boolean exists(String sessionId)
      Cheap existence check: consults the in-memory index and verifies the session file exists on disk, without parsing any JSON. Unlike the default implementation it never throws on corrupt session files.
      Specified by:
      exists in interface SessionStore
      Parameters:
      sessionId - the session ID
      Returns:
      true if exists

    • evictExpired

      public int evictExpired()
      Evicts sessions older than the configured maxAgeDays (based on session start time). No-op when retention is disabled (maxAgeDays <= 0).

      Runs once at construction; call explicitly to re-apply the policy. Never runs during save(AgentSession) to keep saves cheap.

      Returns:
      number of evicted sessions

    • clear

      public void clear()
      Description copied from interface: SessionStore
      Clears all sessions (use with caution).
      Specified by:
      clear in interface SessionStore