Documentation
¶
Overview ¶
Package tree implements the tree-structured session JSONL format per registration spec §2.6. A session is a single append-only `.jsonl` file plus a tiny sidecar pointer file recording the current active head. Every entry carries an `id` and a `parentId` (empty for the root). Branching is cheap (the JSONL grows, the sidecar moves); rewind / fork / branch-summary operations are implemented by moving the head pointer without truncating history.
Index ¶
- type AppendHook
- type Entry
- type EntryKind
- type Tree
- func (t *Tree) All(ctx context.Context) ([]Entry, error)
- func (t *Tree) Append(ctx context.Context, e Entry) (Entry, error)
- func (t *Tree) Fork(ctx context.Context, id string) error
- func (t *Tree) Head() (string, error)
- func (t *Tree) JSONLPath() string
- func (t *Tree) Replay(ctx context.Context) ([]Entry, error)
- func (t *Tree) SetAppendHook(h AppendHook)
- func (t *Tree) SetHead(ctx context.Context, id string) error
- func (t *Tree) SidecarPath() string
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AppendHook ¶
type AppendHook func(Entry)
Tree is a handle on a session's JSONL + sidecar pair. Safe for concurrent use within a single process — all mutating operations take the tree mutex. Cross-process concurrency is NOT supported (session files are owned by a single agent runtime). AppendHook is invoked (synchronously, after the tree mutex is released) for each successful Append. Used by the agent runtime to forward entries upward as session.entry.appended frames for Nexus- side observability. Implementations must not call back into the tree; they should hand the entry off to a channel / queue.
type Entry ¶
type Entry struct {
ID string `json:"id"`
ParentID string `json:"parentId,omitempty"`
Kind EntryKind `json:"kind"`
TS time.Time `json:"ts"`
Payload map[string]any `json:"payload,omitempty"`
}
Entry is a single session-tree record as stored on disk.
type EntryKind ¶
type EntryKind string
EntryKind mirrors the spec §2.6 kinds. These are the canonical session-tree kinds; providers.EntryKind is a superset (adds things like custom.*) but the tree owns the ones listed here.
type Tree ¶
type Tree struct {
// contains filtered or unexported fields
}
func Open ¶
Open opens (or creates) the session files at dir/<name>.jsonl and dir/<name>.head.json. Creates the directory if missing. Works on both a brand-new session and an existing one.
func (*Tree) All ¶
All returns every entry in the log, regardless of which branch they belong to. Useful for export / backup / audit. Ordered by file position, not timestamp.
func (*Tree) Append ¶
Append writes a new entry to the JSONL, records it as the new active head, and returns it with ID and TS populated. ParentID defaults to the current head if the caller leaves it empty; pass a specific ParentID to branch off an earlier entry.
If an AppendHook is installed, it fires after the mutex is released with the written entry — the hook gets the fully populated Entry (id + ts + parent) and can forward it.
func (*Tree) Fork ¶
Fork sets the head to an earlier entry. A subsequent Append will link its ParentID to this entry, creating a new branch in the tree. Shorthand for SetHead; exists so callers can self-document intent.
func (*Tree) Head ¶
Head returns the current active-head entry ID. Empty string on a brand-new session.
func (*Tree) Replay ¶
Replay returns the entries on the active branch, oldest first. Walks from the current head back along parentId links, collecting matching entries, then reverses. Callers get a chronological view of the session regardless of where the JSONL physically stored branches.
func (*Tree) SetAppendHook ¶
func (t *Tree) SetAppendHook(h AppendHook)
SetAppendHook installs a callback that fires after each successful Append. The hook runs on the Append caller's goroutine, after the tree mutex has been released, so it must not reach back into the tree or do anything slow. Pass nil to clear.
func (*Tree) SetHead ¶
SetHead moves the active head pointer to the given entry ID. Intended for rewind / fork operations — the entry must already exist in the JSONL (otherwise the next Replay would fail).
func (*Tree) SidecarPath ¶
SidecarPath returns the head-pointer file path.
Source Files