jsonl

Documentation

Overview

Package jsonl is the default session store: one append-only JSONL file per session under a root directory, laid out as

<root>/<project-key>/<created-at>_<session-id>.jsonl

where the project key derives from the session's working directory. Each Append writes one line; a SyncPolicy decides when the file is fsynced. Opening a session whose last line was cut short by a crash drops that line so later appends produce a valid file.

Index

• Variables
• func ProjectKey(cwd string) string
• type LockInfo
• type Option
  • func WithSync(p SyncPolicy) Option
• type Store
  • func Open(root string, opts ...Option) (*Store, error)
  • func (s *Store) Append(ctx context.Context, sessionID string, e agentsession.Entry) (string, error)
  • func (s *Store) BreakLock(id string) error
  • func (s *Store) Close() error
  • func (s *Store) Create(ctx context.Context, h agentsession.Header) (*agentsession.Session, error)
  • func (s *Store) Delete(ctx context.Context, id string) error
  • func (s *Store) List(ctx context.Context, f agentsession.ListFilter) iter.Seq2[agentsession.Summary, error]
  • func (s *Store) LockHolder(id string) (*LockInfo, error)
  • func (s *Store) Open(ctx context.Context, id string) (*agentsession.Session, error)
  • func (s *Store) Path(id string) (string, error)
  • func (s *Store) Release(id string) error
  • func (s *Store) Root() string
  • func (s *Store) Sync(ctx context.Context, id string) error
• type SyncPolicy

Variables

var ErrSessionLocked = errors.New("jsonl: session is open in another process")

ErrSessionLocked is returned by Create, Open and Append when another process holds the session. The error's message names the holder; BreakLock removes a lock the caller has decided is stale.

Functions

func ProjectKey

func ProjectKey(cwd string) string

ProjectKey derives the directory name for a working directory: the leading separator stripped and path separators and colons replaced by "-", so "/home/u/proj" becomes "home-u-proj". An empty directory maps to "default".

Types

type LockInfo

type LockInfo struct {
	PID   int       `json:"pid"`
	Host  string    `json:"host,omitempty"`
	Since time.Time `json:"since"`
}

LockInfo describes the holder of a session lock.

type Option

type Option func(*Store)

Option configures a Store.

func WithSync

func WithSync(p SyncPolicy) Option

WithSync sets the sync policy.

type Store

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

Store is a file-backed agentsession.Store. It is safe for concurrent use within one process. Across processes each open session is guarded by an advisory lock file beside it, <file>.lock, so a second process that opens the same session gets ErrSessionLocked instead of interleaving lines with the first. The lock is released by Release, Delete and Close; a lock left by a process on this host that no longer runs is taken over on the next open, and BreakLock clears one from any other holder.

func Open

func Open(root string, opts ...Option) (*Store, error)

Open returns a store over root, creating the directory if needed.

func (*Store) Append

func (s *Store) Append(ctx context.Context, sessionID string, e agentsession.Entry) (string, error)

Append implements agentsession.Store: the entry joins the in-memory tree, then its line is written and synced according to the policy.

func (*Store) BreakLock

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

BreakLock removes a session's lock whoever holds it. Use it when Open reports ErrSessionLocked and the caller has confirmed the holder is gone, for example a process on another host that crashed. Breaking the lock of a live writer lets two processes append to one file.

func (*Store) Close

func (s *Store) Close() error

Close syncs and closes every open session file.

func (*Store) Create

func (s *Store) Create(ctx context.Context, h agentsession.Header) (*agentsession.Session, error)

Create implements agentsession.Store. The file is created with the header line and synced before Create returns.

func (*Store) Delete

func (s *Store) Delete(ctx context.Context, id string) error

Delete implements agentsession.Store: the file is removed and the session forgotten.

func (*Store) List

func (s *Store) List(ctx context.Context, f agentsession.ListFilter) iter.Seq2[agentsession.Summary, error]

List implements agentsession.Store by reading the header line of every session file under the root. Files that do not parse are reported as errors in the sequence and skipped.

func (*Store) LockHolder

func (s *Store) LockHolder(id string) (*LockInfo, error)

LockHolder reports who holds a session's lock, or nil when it is free. It reads the lock file and does not consult this store's open sessions, so a session this store holds is reported as locked by this process.

func (*Store) Open

func (s *Store) Open(ctx context.Context, id string) (*agentsession.Session, error)

Open implements agentsession.Store. A session already open in this store is returned as is; otherwise its lock is taken and its file is read. A final line left incomplete by a crash is reported through Session.Truncated and removed from the file so later appends continue a valid file. Open returns ErrSessionLocked when another process holds the session.

func (*Store) Path

func (s *Store) Path(id string) (string, error)

Path returns the file a session lives in, whether or not it is open.

func (*Store) Release

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

Release syncs and closes an open session's file and drops its lock without deleting it. The session can be opened again later, by this or another process.

func (*Store) Root

func (s *Store) Root() string

Root returns the store's directory.

func (*Store) Sync

func (s *Store) Sync(ctx context.Context, id string) error

Sync fsyncs an open session's file.

type SyncPolicy

type SyncPolicy int

SyncPolicy says when the store fsyncs a session file.

const (
	// SyncEveryAppend fsyncs after every line. It is the default.
	SyncEveryAppend SyncPolicy = iota
	// SyncOnResponse fsyncs after a response entry, which the format
	// recommends as the minimum, and after a compaction or a branch
	// summary, which are as expensive to lose.
	SyncOnResponse
	// SyncNever leaves syncing to the operating system and to explicit
	// calls to Store.Sync.
	SyncNever
)