session

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Sep 25, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package session implements the durable harness session: the write-once entry tree, bound values and lists, the usage ledger, the storage contract, the Session mutation line, Branch capabilities, forks, and the in-memory backend.

Index

Constants

View Source
const (
	JSONLFormatVersion  = 4
	JSONLStorageVersion = 1
)

JSONLFormatVersion and JSONLStorageVersion belong to the upstream file format.

View Source
const (
	OperationKindRun        = "run"
	OperationKindCompaction = "compaction"
	OperationKindNavigation = "navigation"
)

Operation intent kinds.

View Source
const (
	ControlRunning         = "running"
	ControlCancelRequested = "cancel_requested"
)

Control statuses.

View Source
const (
	TerminalCompleted = "completed"
	TerminalDeclined  = "declined"
	TerminalAborted   = "aborted"
	TerminalFailed    = "failed"
)

TerminalStatus values.

View Source
const (
	ContinuationNeedAssistant = "need_assistant"
	ContinuationMayFinish     = "may_finish"
)

Continuation kinds.

View Source
const (
	InboxSteer    = "steer"
	InboxFollowUp = "followUp"
	InboxNextRun  = "nextRun"
	InboxWrite    = "write"
)

Inbox item kinds.

View Source
const (
	ToolCallPlanned       = "planned"
	ToolCallEffectPending = "effect_pending"
	ToolCallOutcomeReady  = "outcome_ready"
	ToolCallCompleted     = "completed"
)

Tool call statuses.

View Source
const (
	ToolExecutionSequential = "sequential"
	ToolExecutionParallel   = "parallel"
)

Tool execution modes.

View Source
const (
	BoundaryResumeCheckpoint = "resume_checkpoint"
	BoundaryFinish           = "finish"
	BoundaryCommitNavigation = "commit_navigation"
)

Result boundary kinds.

View Source
const (
	SummaryReasonManual    = "manual"
	SummaryReasonThreshold = "threshold"
	SummaryReasonOverflow  = "overflow"
)

Summary task reasons.

View Source
const (
	PendingEntryMessage = "message"
	PendingEntryCustom  = "custom"
)

Pending entry types.

View Source
const (
	PreparationCompaction    = "compaction"
	PreparationBranchSummary = "branch_summary"
)

Structural preparation kinds.

View Source
const (
	OrderNewestFirst = "newestFirst"
	OrderOldestFirst = "oldestFirst"
	OrderAsc         = "asc"
	OrderDesc        = "desc"
)

Branch scan orders.

View Source
const (
	ForkScopeBranch = "branch"
	ForkScopeTree   = "tree"
)

Fork scopes.

View Source
const (
	ForkPositionBefore = "before"
	ForkPositionAt     = "at"
)

Fork positions.

View Source
const (
	KindValue = "value"
	KindList  = "list"
)

Address kinds.

Variables

View Source
var ErrSessionClosed = errors.New("Session is closed")

ErrSessionClosed rejects Session calls after close.

View Source
var SessionName = MustValue[string]("pi.session.name", "")

SessionName addresses the session name.

Functions

func BuildSessionContext

func BuildSessionContext(ctx context.Context, pathEntries []Entry, options *SessionContextBuildOptions) ([]agent.AgentMessage, error)

BuildSessionContext projects a branch path into model context: the latest compaction checkpoint and later entries, with custom entries run through their projectors in path order. A projector error aborts the build.

func IsPendingAssistant

func IsPendingAssistant(message agent.AgentMessage) bool

IsPendingAssistant reports whether message is an assistant message whose stopReason is "pending".

func Mutate

func Mutate[T any](ctx context.Context, session Session, mutation func(ctx context.Context, mutator SessionMutator) (T, error)) (T, error)

Mutate runs a typed callback over a Session's mutation line.

func PublishFileAtomically

func PublishFileAtomically(ctx context.Context, fs harness.FileSystem, path string, write func(appendText func(string) error) error) (err error)

PublishFileAtomically publishes only after the synchronous writer succeeds.

func SerializeJsonlTransaction

func SerializeJsonlTransaction(writes []CommittedWrite) (string, error)

SerializeJsonlTransaction uses the single-write form for one write and arrays otherwise.

func SessionEntryToContextMessages

func SessionEntryToContextMessages(entry Entry) []agent.AgentMessage

SessionEntryToContextMessages projects one non-custom entry into model context; custom entries project nothing here.

func UUIDv7

func UUIDv7(timestampMs *int64) (string, error)

UUIDv7 returns a time-ordered UUIDv7. A nil timestamp uses the wall clock and never moves backwards; a supplied timestamp is preserved exactly for follower ids. A process-wide 41-bit sequence seeded from randomness keeps ids unique and ordered within one millisecond.

func ValidateCommittedWrites

func ValidateCommittedWrites(writes []CommittedWrite, firstSeq int64, state CommitValidationState) error

ValidateCommittedWrites checks sequence monotonicity, the shared entry/usage id namespace, and that every entry parent exists earlier.

Types

type Branch

type Branch interface {
	Name() string
	// GetTipID returns nil for an empty Branch.
	GetTipID(ctx context.Context) (*string, error)
	FindEntries(ctx context.Context, query *BranchScan) ([]Entry, error)
	// FindEntry returns nil when nothing matches.
	FindEntry(ctx context.Context, query *BranchScan) (*Entry, error)
	AppendMessage(ctx context.Context, message agent.AgentMessage) (string, error)
	// AppendCustomEntry appends a custom entry; nil data means no data.
	AppendCustomEntry(ctx context.Context, customType string, data *JsonValue) (string, error)
}

Branch is one named data path with a movable tip.

type BranchForkSource

type BranchForkSource struct {
	Tip         *string
	HasTip      bool
	GetParent   func(entryID string) (parentID *string, ok bool)
	SelectEntry func(entryID string)
}

BranchForkSource answers the lookups branch selection needs. HasTip is false for an unknown Branch; Tip nil is an empty Branch. GetParent reports ok false for a missing entry.

type BranchScan

type BranchScan struct {
	Start      *string
	StopAtType EntryType
	StopAtID   string
	Type       EntryType
	CustomType string
	// Order is OrderNewestFirst (default) or OrderOldestFirst.
	Order  string
	Limit  *int
	Cursor *EntryCursor
}

BranchScan queries the path from Start (default: the receiver's tip) toward the root. Empty strings and nil pointers mean the member is absent.

type CheckpointData

type CheckpointData struct {
	Continuation   Continuation `json:"continuation"`
	TriggerEntryID string       `json:"triggerEntryId"`
}

CheckpointData is the checkpoint payload.

type CommitResult

type CommitResult struct {
	FirstSeq  int64        `json:"firstSeq"`
	Seqs      []int64      `json:"seqs"`
	Timestamp int64        `json:"timestamp"`
	Stats     SessionStats `json:"stats"`
}

CommitResult reports the sequences and timestamp one commit assigned and the session totals immediately after it applied.

type CommitValidationState

type CommitValidationState struct {
	HasEntryOrUsageID func(id string) bool
	HasEntryID        func(id string) bool
}

CommitValidationState answers the id lookups commit validation needs.

type CommittedEntryWrite

type CommittedEntryWrite struct{ Entry Entry }

CommittedEntryWrite is an inserted entry with its seq and timestamp.

func (CommittedEntryWrite) CommittedSeq

func (write CommittedEntryWrite) CommittedSeq() int64

type CommittedListAppendWrite

type CommittedListAppendWrite struct {
	Seq       int64
	Namespace string
	Key       string
	Value     any
}

CommittedListAppendWrite is a sequenced list append.

func (CommittedListAppendWrite) CommittedSeq

func (write CommittedListAppendWrite) CommittedSeq() int64

type CommittedListDeleteWrite

type CommittedListDeleteWrite struct {
	Seq       int64
	Namespace string
	Key       string
}

CommittedListDeleteWrite is a sequenced whole-list delete.

func (CommittedListDeleteWrite) CommittedSeq

func (write CommittedListDeleteWrite) CommittedSeq() int64

type CommittedUsageWrite

type CommittedUsageWrite struct{ Row UsageRow }

CommittedUsageWrite is an inserted ledger row with its seq.

func (CommittedUsageWrite) CommittedSeq

func (write CommittedUsageWrite) CommittedSeq() int64

type CommittedValueDeleteWrite

type CommittedValueDeleteWrite struct {
	Seq       int64
	Namespace string
	Key       string
}

CommittedValueDeleteWrite is a sequenced scalar delete.

func (CommittedValueDeleteWrite) CommittedSeq

func (write CommittedValueDeleteWrite) CommittedSeq() int64

type CommittedValueSetWrite

type CommittedValueSetWrite struct {
	Seq       int64
	Namespace string
	Key       string
	Value     any
}

CommittedValueSetWrite is a sequenced scalar set.

func (CommittedValueSetWrite) CommittedSeq

func (write CommittedValueSetWrite) CommittedSeq() int64

type CommittedWrite

type CommittedWrite interface{ CommittedSeq() int64 }

CommittedWrite is one write with its assigned sequence: CommittedEntryWrite, CommittedUsageWrite, CommittedValueSetWrite, CommittedValueDeleteWrite, CommittedListAppendWrite, or CommittedListDeleteWrite.

func CommitWrite

func CommitWrite(write Write, seq, timestamp int64) (CommittedWrite, error)

CommitWrite assigns one write its sequence and the transaction timestamp.

func ParseJsonlTransaction

func ParseJsonlTransaction(line string) ([]CommittedWrite, error)

ParseJsonlTransaction decodes one complete transaction without applying it.

func ProjectForkCurrentStateWrite

func ProjectForkCurrentStateWrite(write CommittedWrite, plan ForkCurrentStatePlan, isEntryCopied func(entryID string) bool) (CommittedWrite, bool, error)

ProjectForkCurrentStateWrite projects one current scalar row or surviving list element (CommittedValueSetWrite or CommittedListAppendWrite) into destination state. ok is false when the row is excluded; an error rejects a surviving row in an undeclared reserved namespace.

type Continuation

type Continuation struct {
	Kind                  string `json:"kind"`
	OverflowRecoveryUsed  bool   `json:"overflowRecoveryUsed"`
	IncludeFinalAssistant bool   `json:"includeFinalAssistant"`
}

Continuation selects the checkpoint's next step: need_assistant uses OverflowRecoveryUsed; may_finish uses IncludeFinalAssistant.

func (Continuation) MarshalJSON

func (continuation Continuation) MarshalJSON() ([]byte, error)

MarshalJSON emits the members of Kind.

type Control

type Control struct {
	Status      string `json:"status"`
	RequestedAt int64  `json:"requestedAt"`
}

Control is the orthogonal cancellation state of an operation.

func (Control) MarshalJSON

func (control Control) MarshalJSON() ([]byte, error)

MarshalJSON emits requestedAt only for cancellation.

type DurableFileOperations

type DurableFileOperations struct {
	Read    []string `json:"read"`
	Written []string `json:"written"`
	Edited  []string `json:"edited"`
}

DurableFileOperations are the file paths touched by summarized content.

func (DurableFileOperations) MarshalJSON

func (operations DurableFileOperations) MarshalJSON() ([]byte, error)

MarshalJSON keeps empty path lists as [].

type DurableStructuralPreparation

type DurableStructuralPreparation struct {
	Kind                string                     `json:"kind"`
	MessagesToSummarize []agent.AgentMessage       `json:"messagesToSummarize"`
	TurnPrefixMessages  []agent.AgentMessage       `json:"turnPrefixMessages"`
	RetainedTail        []agent.AgentMessage       `json:"retainedTail"`
	IsSplitTurn         bool                       `json:"isSplitTurn"`
	TokensBefore        int                        `json:"tokensBefore"`
	PreviousSummary     *string                    `json:"previousSummary,omitempty"`
	Messages            []agent.AgentMessage       `json:"messages"`
	FileOps             DurableFileOperations      `json:"fileOps"`
	Settings            harness.CompactionSettings `json:"settings"`
	TotalTokens         int                        `json:"totalTokens"`
}

DurableStructuralPreparation is the immutable content of one summary task: compaction members, or branch_summary Messages and TotalTokens.

func (DurableStructuralPreparation) MarshalJSON

func (preparation DurableStructuralPreparation) MarshalJSON() ([]byte, error)

MarshalJSON emits the members of Kind.

type Entry

type Entry struct {
	ID         string
	ParentID   *string
	Seq        int64
	Timestamp  int64
	Type       EntryType
	CustomType string

	// Message entries.
	Message agent.AgentMessage
	// Terminate marks a tool result that ends the run (upstream terminate?: true).
	Terminate bool

	// Compaction and branch-summary entries.
	Summary      string
	RetainedTail []agent.AgentMessage
	TokensBefore int
	Details      *JsonValue
	Usage        *ai.Usage
	FromHook     bool
	FromID       *string

	// Custom entries; nil means the entry has no data.
	Data *JsonValue
}

Entry is one write-once conversation record: placement fields plus the payload of its Type. Fields of other entry types are ignored. As a transaction input (upstream NewEntry) Seq and Timestamp are unset; storage assigns them at commit.

func BuildContextEntries

func BuildContextEntries(pathEntries []Entry) []Entry

BuildContextEntries returns the latest compaction and every entry after it, or the whole path when no compaction exists.

func MaterializeCommittedEntry

func MaterializeCommittedEntry(entry Entry, seq, timestamp int64) Entry

MaterializeCommittedEntry stamps a transaction entry with seq and timestamp.

func (Entry) MarshalJSON

func (entry Entry) MarshalJSON() ([]byte, error)

MarshalJSON emits the upstream entry shape for Type.

func (*Entry) UnmarshalJSON

func (entry *Entry) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes any entry type, keeping explicit null details/data distinct from absent members.

type EntryCursor

type EntryCursor struct {
	Seq int64 `json:"seq"`
}

EntryCursor is an exclusive sequence cursor.

type EntryProjector

type EntryProjector func(ctx context.Context, entry Entry) ([]agent.AgentMessage, error)

EntryProjector converts an application-defined custom entry into model context; nil messages project nothing.

type EntryQuery

type EntryQuery struct {
	Type       EntryType
	CustomType string
	Order      string
	Limit      *int
	Cursor     *EntryCursor
}

EntryQuery queries session-wide entries; Order defaults to OrderDesc.

type EntryScan

type EntryScan struct {
	Type       EntryType
	CustomType string
	FromSeq    *int64
	ToSeq      *int64
	// Order is OrderAsc (default) or OrderDesc.
	Order string
	Limit *int
}

EntryScan queries the session-wide entry inventory.

type EntryStructure

type EntryStructure struct {
	ID         string    `json:"id"`
	ParentID   *string   `json:"parentId"`
	Seq        int64     `json:"seq"`
	Timestamp  int64     `json:"timestamp"`
	Type       EntryType `json:"type"`
	CustomType string    `json:"customType,omitempty"`
}

EntryStructure is an entry without payload fields.

func EntryStructureOf

func EntryStructureOf(entry Entry) EntryStructure

EntryStructureOf strips an entry to its placement fields.

type EntryType

type EntryType string

EntryType is the structural type of one entry.

const (
	EntryTypeMessage       EntryType = "message"
	EntryTypeCompaction    EntryType = "compaction"
	EntryTypeBranchSummary EntryType = "branch_summary"
	EntryTypeCustom        EntryType = "custom"
)

type EntryWrite

type EntryWrite struct{ Entry Entry }

EntryWrite inserts one complete entry.

func InsertEntry

func InsertEntry(entry Entry) EntryWrite

InsertEntry constructs an entry insert write.

func (EntryWrite) MarshalJSON

func (write EntryWrite) MarshalJSON() ([]byte, error)

MarshalJSON emits {kind: "entry", entry} with the unplaced entry.

type ForkCurrentStatePlan

type ForkCurrentStatePlan struct {
	Scope          string
	Branch         string
	DestinationTip *string
}

ForkCurrentStatePlan is the scope-specific projection plan for current state: tree scope, or one Branch with its destination tip.

func SelectBranchFork

func SelectBranchFork(options ForkOptions, source BranchForkSource) (ForkCurrentStatePlan, error)

SelectBranchFork walks the source tip ancestry, selects the forked path, and returns the destination tip.

type ForkDestinationSnapshot

type ForkDestinationSnapshot struct {
	Entries      []Entry
	ScalarValues []StoredValue[any]
	NextSeq      int64
}

ForkDestinationSnapshot is the complete logical state of a fork destination. Entries keep the upstream selection order.

func CreateForkSnapshot

func CreateForkSnapshot(source ForkSourceSnapshot, options ForkOptions) (ForkDestinationSnapshot, error)

CreateForkSnapshot builds the complete logical state of a forked destination session, re-sequencing projected scalar values after the copied entries.

type ForkOptions

type ForkOptions struct {
	Scope  string
	Branch string
	// EntryID must lie on the source Branch's tip ancestry; nil selects the tip.
	EntryID *string
	// Position is ForkPositionAt (default) or ForkPositionBefore.
	Position string
	ID       string
}

ForkOptions select a repository fork. Branch scope copies one path from a complete configured source AgentLane; tree scope copies the whole tree and every Branch tip. Empty strings and nil pointers are absent.

type ForkSourceSnapshot

type ForkSourceSnapshot struct {
	Entries      []Entry
	ScalarValues []StoredValue[any]
	// EntriesIncomplete reports that a backend supplied only the requested
	// branch rather than the full tree (upstream entriesComplete: false).
	EntriesIncomplete bool
}

ForkSourceSnapshot is one coherent source read for a streaming fork.

type GenerationContext

type GenerationContext struct {
	StepID               string                            `json:"stepId"`
	TriggerEntryID       string                            `json:"triggerEntryId"`
	Configuration        LaneConfiguration                 `json:"configuration"`
	StreamOptions        harness.AgentHarnessStreamOptions `json:"streamOptions"`
	RetryPolicy          NormalizedRetryPolicy             `json:"retryPolicy"`
	OverflowRecoveryUsed bool                              `json:"overflowRecoveryUsed"`
}

GenerationContext is the assistant request snapshot of one step.

type IdGenerator

type IdGenerator interface {
	Next(timestampMs *int64) string
}

IdGenerator mints session-unique ids. A non-nil timestampMs is the exact time prefix of the minted id.

var UUIDv7Generator IdGenerator = IdGeneratorFunc(func(timestampMs *int64) string {
	id, err := UUIDv7(timestampMs)
	if err != nil {
		panic(err)
	}
	return id
})

UUIDv7Generator is the default UUIDv7 IdGenerator. An out-of-range supplied timestamp is a trusted-programming defect and panics, like the upstream RangeError.

type IdGeneratorFunc

type IdGeneratorFunc func(timestampMs *int64) string

IdGeneratorFunc adapts a function to IdGenerator.

func (IdGeneratorFunc) Next

func (generator IdGeneratorFunc) Next(timestampMs *int64) string

Next calls the function.

type InMemoryStorageState

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

InMemoryStorageState is the complete materialized session state shared by MemoryStorage and JSONL storage. It is unsuitable for database backends and long sessions that may not fit in memory. It is not safe for concurrent use; its owner serializes access.

func NewInMemoryStorageState

func NewInMemoryStorageState() *InMemoryStorageState

NewInMemoryStorageState returns empty state whose next sequence is 1.

func (*InMemoryStorageState) AdvanceNextSeq

func (state *InMemoryStorageState) AdvanceNextSeq(nextSeq int64) error

AdvanceNextSeq raises the sequence high-water mark.

func (*InMemoryStorageState) ApplyValidated

func (state *InMemoryStorageState) ApplyValidated(writes []CommittedWrite) SessionStats

ApplyValidated applies writes already accepted by ValidateCommitted and returns the post-apply totals.

func (*InMemoryStorageState) CreateFork

func (state *InMemoryStorageState) CreateFork(options ForkOptions) (*InMemoryStorageState, error)

CreateFork constructs destination state directly from this state.

func (*InMemoryStorageState) GetEntries

func (state *InMemoryStorageState) GetEntries(ids []string) map[string]Entry

GetEntries returns the requested existing entries.

func (*InMemoryStorageState) GetNextSeq

func (state *InMemoryStorageState) GetNextSeq() int64

GetNextSeq returns the next sequence to assign.

func (*InMemoryStorageState) GetStats

func (state *InMemoryStorageState) GetStats() SessionStats

GetStats returns the maintained totals.

func (*InMemoryStorageState) GetValue

func (state *InMemoryStorageState) GetValue(address StoredAddressBase) *StoredValue[any]

GetValue returns one current value, or nil.

func (*InMemoryStorageState) PrepareCommit

func (state *InMemoryStorageState) PrepareCommit(writes []Write, timestamp int64) (PreparedCommit, error)

PrepareCommit sequences and validates writes at timestamp without applying them.

func (*InMemoryStorageState) ReadList

func (state *InMemoryStorageState) ReadList(address StoredAddressBase, options *ListReadOptions) ([]ListElement[any], error)

ReadList returns one ordered page of a list.

func (*InMemoryStorageState) ScanBranch

func (state *InMemoryStorageState) ScanBranch(query StorageBranchScan) ([]Entry, error)

ScanBranch walks the path from query.Start toward the root, orders it, stops inclusively at the first stop match, filters, applies the exclusive cursor, then the limit.

func (*InMemoryStorageState) ScanBranchStructure

func (state *InMemoryStorageState) ScanBranchStructure(query StorageBranchScan) ([]EntryStructure, error)

ScanBranchStructure is ScanBranch without payload fields.

func (*InMemoryStorageState) ScanEntries

func (state *InMemoryStorageState) ScanEntries(query EntryScan) []Entry

ScanEntries scans the session-wide entry inventory in sequence order.

func (*InMemoryStorageState) ScanUsage

func (state *InMemoryStorageState) ScanUsage(query UsageScan) []UsageRow

ScanUsage scans the usage ledger in sequence order.

func (*InMemoryStorageState) ScanValues

func (state *InMemoryStorageState) ScanValues(prefix StoredAddressBase) []StoredValue[any]

ScanValues returns the namespace's values whose key starts with the prefix key, in code-point key order.

func (*InMemoryStorageState) ValidateCommitted

func (state *InMemoryStorageState) ValidateCommitted(writes []CommittedWrite) error

ValidateCommitted validates sequenced writes against current state.

type InboxItem

type InboxItem struct {
	EntryID string `json:"entryId"`
	Kind    string `json:"kind"`
}

InboxItem is one ordered lane inbox item referencing its pending entry.

type JsonValue

type JsonValue = harness.JsonValue

JsonValue is a strict JSON value.

type JsonlParsedSessionHeader

type JsonlParsedSessionHeader struct {
	Header *JsonlStorageHeader
	Legacy *LegacyV3SessionHeader
}

JsonlParsedSessionHeader discriminates upstream file formats.

func ParseJsonlSessionHeader

func ParseJsonlSessionHeader(line string) (JsonlParsedSessionHeader, error)

ParseJsonlSessionHeader recognizes the current and upstream legacy header shapes.

type JsonlSessionListOptions

type JsonlSessionListOptions struct{ Cwd *string }

JsonlSessionListOptions optionally restricts discovery to a working directory.

type JsonlSessionRepo

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

JsonlSessionRepo owns exclusive handles and discovery for format-4 sessions.

func NewJsonlSessionRepo

func NewJsonlSessionRepo(options JsonlSessionRepoOptions) *JsonlSessionRepo

func (*JsonlSessionRepo) Close

func (repo *JsonlSessionRepo) Close(context.Context) error

Close seals repository admission; existing session handles own their own lifetime.

func (*JsonlSessionRepo) Create

func (repo *JsonlSessionRepo) Create(ctx context.Context, options SessionCreateOptions) (opened Session, err error)

Create publishes an empty session only after its complete header is durable.

func (*JsonlSessionRepo) Delete

func (repo *JsonlSessionRepo) Delete(ctx context.Context, metadata SessionMetadata) error

Delete removes a closed session file.

func (*JsonlSessionRepo) Fork

func (repo *JsonlSessionRepo) Fork(ctx context.Context, source SessionMetadata, options ForkOptions) (opened Session, err error)

Fork indexes source structure and streams only selected current state into a new file.

func (*JsonlSessionRepo) List

List discovers valid headers newest first, optionally within one exact cwd.

func (*JsonlSessionRepo) Open

func (repo *JsonlSessionRepo) Open(ctx context.Context, metadata SessionMetadata) (Session, error)

Open validates identity and storage version before granting an exclusive handle.

type JsonlSessionRepoOptions

type JsonlSessionRepoOptions struct {
	FileSystem   harness.FileSystem
	SessionsRoot string
	Now          func() int64
}

JsonlSessionRepoOptions configures the file-backed repository.

type JsonlStorage

type JsonlStorage struct {
	Header JsonlStorageHeader
	// contains filtered or unexported fields
}

JsonlStorage serializes append transactions and materializes their committed state.

func CreateJsonlStorage

func CreateJsonlStorage(ctx context.Context, options JsonlStorageOptions, header JsonlStorageHeader, initial []Write) (*JsonlStorage, error)

CreateJsonlStorage atomically writes a header and optional initial transaction.

func OpenJsonlStorage

func OpenJsonlStorage(ctx context.Context, options JsonlStorageOptions) (*JsonlStorage, error)

OpenJsonlStorage replays complete transactions and repairs only a torn format-4 tail.

func (*JsonlStorage) CaptureForkNextSeq

func (storage *JsonlStorage) CaptureForkNextSeq(context.Context) (int64, error)

CaptureForkNextSeq snapshots the next sequence at a serialized commit boundary.

func (*JsonlStorage) Close

func (storage *JsonlStorage) Close(context.Context) error

Close rejects later calls and waits for admitted commits.

func (*JsonlStorage) Commit

func (storage *JsonlStorage) Commit(ctx context.Context, writes []Write) (CommitResult, error)

Commit appends one complete transaction before exposing its in-memory effects.

func (*JsonlStorage) GetEntries

func (storage *JsonlStorage) GetEntries(_ context.Context, ids []string) (map[string]Entry, error)

func (*JsonlStorage) GetStats

func (storage *JsonlStorage) GetStats(context.Context) (SessionStats, error)

func (*JsonlStorage) GetValue

func (storage *JsonlStorage) GetValue(_ context.Context, address StoredAddressBase) (*StoredValue[any], error)

func (*JsonlStorage) IsLegacyV3

func (storage *JsonlStorage) IsLegacyV3() bool

IsLegacyV3 reports whether the backing file still requires first-write upgrade.

func (*JsonlStorage) ReadList

func (storage *JsonlStorage) ReadList(_ context.Context, address StoredAddressBase, options *ListReadOptions) ([]ListElement[any], error)

func (*JsonlStorage) ScanBranch

func (storage *JsonlStorage) ScanBranch(_ context.Context, query StorageBranchScan) ([]Entry, error)

func (*JsonlStorage) ScanBranchStructure

func (storage *JsonlStorage) ScanBranchStructure(_ context.Context, query StorageBranchScan) ([]EntryStructure, error)

func (*JsonlStorage) ScanEntries

func (storage *JsonlStorage) ScanEntries(_ context.Context, query EntryScan) ([]Entry, error)

func (*JsonlStorage) ScanUsage

func (storage *JsonlStorage) ScanUsage(_ context.Context, query UsageScan) ([]UsageRow, error)

func (*JsonlStorage) ScanValues

func (storage *JsonlStorage) ScanValues(_ context.Context, address StoredAddressBase) ([]StoredValue[any], error)

type JsonlStorageHeader

type JsonlStorageHeader struct {
	V                       int    `json:"v"`
	Kind                    string `json:"kind"`
	ID                      string `json:"id"`
	StorageVersion          int    `json:"storageVersion"`
	CreatedAt               int64  `json:"createdAt"`
	Cwd                     string `json:"cwd"`
	ParentSessionID         string `json:"parentSessionId,omitempty"`
	LegacyParentSessionPath string `json:"legacyParentSessionPath,omitempty"`
	NextSeq                 *int64 `json:"nextSeq,omitempty"`
}

JsonlStorageHeader is the upstream format-4 file header.

type JsonlStorageOptions

type JsonlStorageOptions struct {
	FileSystem harness.FileSystem
	Path       string
	Now        func() int64
}

JsonlStorageOptions supplies the filesystem and destination path.

type LaneConfiguration

type LaneConfiguration struct {
	Model           ModelRef         `json:"model"`
	ThinkingLevel   ai.ThinkingLevel `json:"thinkingLevel"`
	ActiveToolNames []string         `json:"activeToolNames"`
}

LaneConfiguration is the total configuration of one AgentLane.

func (LaneConfiguration) MarshalJSON

func (configuration LaneConfiguration) MarshalJSON() ([]byte, error)

MarshalJSON keeps an empty tool list as [].

type LaneState

type LaneState struct {
	CurrentOperationID *string     `json:"currentOperationId"`
	LastOperationID    *string     `json:"lastOperationId"`
	Inbox              []InboxItem `json:"inbox"`
}

LaneState is the lane's current/last operation ids and ordered inbox.

func (LaneState) MarshalJSON

func (state LaneState) MarshalJSON() ([]byte, error)

MarshalJSON keeps an empty inbox as [].

type LegacyV3SessionHeader

type LegacyV3SessionHeader struct {
	Type          string  `json:"type"`
	Version       int     `json:"version"`
	ID            string  `json:"id"`
	Timestamp     string  `json:"timestamp"`
	Cwd           string  `json:"cwd"`
	ParentSession *string `json:"parentSession,omitempty"`
}

LegacyV3SessionHeader is Pi's upstream format-3 header.

type LegacyV3Source

type LegacyV3Source struct {
	Header        JsonlStorageHeader
	ImportedUsage ai.Usage
	NextSeq       int64
	Values        []CommittedValueSetWrite
	// contains filtered or unexported fields
}

LegacyV3Source retains structural metadata and reopens captured payloads for each pass.

func ReadLegacyV3Source

func ReadLegacyV3Source(ctx context.Context, fs harness.FileSystem, path string) (*LegacyV3Source, error)

ReadLegacyV3Source scans complete records without rewriting the source file.

func (*LegacyV3Source) EntryStructures

func (source *LegacyV3Source) EntryStructures() ([]EntryStructure, error)

EntryStructures returns the captured reminted entry identities and ancestry.

func (*LegacyV3Source) TranslateForkEntryID

func (source *LegacyV3Source) TranslateForkEntryID(id string) (string, error)

TranslateForkEntryID requires an actual retained legacy node.

func (*LegacyV3Source) Writes

func (source *LegacyV3Source) Writes(ctx context.Context, selected func(string) bool, yield func(CommittedWrite) error) error

Writes streams selected captured entries and derived values; each call owns its reader and tail cache.

type LineJob

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

LineJob is the pending result of one admitted job.

func (*LineJob) Done

func (job *LineJob) Done() <-chan struct{}

Done is closed when the job settles.

func (*LineJob) Wait

func (job *LineJob) Wait() (any, error)

Wait blocks until the job settles and returns its result.

type ListAppendWrite

type ListAppendWrite struct {
	Namespace string
	Key       string
	Value     any
}

ListAppendWrite appends one list element.

func AppendList

func AppendList[T any](address ValueList[T], element T) ListAppendWrite

AppendList constructs a list append write whose element type is fixed by address.

func (ListAppendWrite) MarshalJSON

func (write ListAppendWrite) MarshalJSON() ([]byte, error)

MarshalJSON emits {kind: "list", op: "append", namespace, key, value}.

type ListCursor

type ListCursor struct {
	Seq int64 `json:"seq"`
}

ListCursor is an exclusive list sequence cursor.

type ListDeleteWrite

type ListDeleteWrite struct{ Namespace, Key string }

ListDeleteWrite deletes a whole list; deleting an absent list is a no-op.

func DeleteList

func DeleteList[T any](address ValueList[T]) ListDeleteWrite

DeleteList constructs a whole-list delete write.

func (ListDeleteWrite) MarshalJSON

func (write ListDeleteWrite) MarshalJSON() ([]byte, error)

MarshalJSON emits {kind: "list", op: "delete", namespace, key}.

type ListElement

type ListElement[T any] struct {
	Seq   int64 `json:"seq"`
	Value T     `json:"value"`
}

ListElement is one immutable list element and its global write sequence.

func ReadList

func ReadList[T any](ctx context.Context, reader SessionReader, address ValueList[T], options *ListReadOptions) ([]ListElement[T], error)

ReadList reads one typed page of a list.

type ListReadOptions

type ListReadOptions struct {
	Cursor *ListCursor
	Order  string
	Limit  *int
}

ListReadOptions page a list; Order defaults to OrderAsc and Limit to 1,000 (clamped to 10,000).

type MemorySessionRepo

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

MemorySessionRepo retains Memory sessions for the life of the process. Each session has at most one open handle at a time.

func NewMemorySessionRepo

func NewMemorySessionRepo(options *MemorySessionRepoOptions) *MemorySessionRepo

NewMemorySessionRepo returns an empty repository.

func (*MemorySessionRepo) Close

func (repo *MemorySessionRepo) Close(ctx context.Context) error

Close closes every retained session; it is idempotent.

func (*MemorySessionRepo) Create

func (repo *MemorySessionRepo) Create(_ context.Context, options SessionCreateOptions) (Session, error)

Create creates an empty session with no Branch.

func (*MemorySessionRepo) Delete

func (repo *MemorySessionRepo) Delete(ctx context.Context, metadata SessionMetadata) error

Delete removes a closed session.

func (*MemorySessionRepo) Fork

func (repo *MemorySessionRepo) Fork(_ context.Context, source SessionMetadata, options ForkOptions) (Session, error)

Fork copies source state into a new open session at one serialized boundary between source commits.

func (*MemorySessionRepo) List

List returns every retained session's metadata in creation order.

func (*MemorySessionRepo) Open

func (repo *MemorySessionRepo) Open(_ context.Context, metadata SessionMetadata) (Session, error)

Open returns a fresh handle to a closed retained session.

type MemorySessionRepoOptions

type MemorySessionRepoOptions struct {
	Now func() int64
}

MemorySessionRepoOptions configure MemorySessionRepo; Now defaults to the wall clock in Unix milliseconds.

type MemoryStorage

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

MemoryStorage is the in-memory Storage backend. Commits and forks serialize on one FIFO queue admitted at call time; reads observe the latest fully applied commit.

func NewMemoryStorage

func NewMemoryStorage(options *MemoryStorageOptions) *MemoryStorage

NewMemoryStorage returns an empty open MemoryStorage.

func (*MemoryStorage) Close

func (storage *MemoryStorage) Close(context.Context) error

Close rejects later calls, drains admitted commits, and is idempotent.

func (*MemoryStorage) Commit

func (storage *MemoryStorage) Commit(_ context.Context, writes []Write) (CommitResult, error)

Commit applies writes atomically after every earlier admitted commit.

func (*MemoryStorage) Fork

func (storage *MemoryStorage) Fork(options ForkOptions) (*MemoryStorage, error)

Fork constructs a destination storage at one serialized boundary between source commits.

func (*MemoryStorage) GetEntries

func (storage *MemoryStorage) GetEntries(_ context.Context, ids []string) (map[string]Entry, error)

GetEntries returns the requested existing entries.

func (*MemoryStorage) GetStats

func (storage *MemoryStorage) GetStats(context.Context) (SessionStats, error)

GetStats returns the maintained totals.

func (*MemoryStorage) GetValue

func (storage *MemoryStorage) GetValue(_ context.Context, address StoredAddressBase) (*StoredValue[any], error)

GetValue returns one current value, or nil.

func (*MemoryStorage) ReadList

func (storage *MemoryStorage) ReadList(_ context.Context, address StoredAddressBase, options *ListReadOptions) ([]ListElement[any], error)

ReadList returns one list page.

func (*MemoryStorage) ScanBranch

func (storage *MemoryStorage) ScanBranch(_ context.Context, query StorageBranchScan) ([]Entry, error)

ScanBranch scans one branch path.

func (*MemoryStorage) ScanBranchStructure

func (storage *MemoryStorage) ScanBranchStructure(_ context.Context, query StorageBranchScan) ([]EntryStructure, error)

ScanBranchStructure scans one branch path without payloads.

func (*MemoryStorage) ScanEntries

func (storage *MemoryStorage) ScanEntries(_ context.Context, query EntryScan) ([]Entry, error)

ScanEntries scans the entry inventory.

func (*MemoryStorage) ScanUsage

func (storage *MemoryStorage) ScanUsage(_ context.Context, query UsageScan) ([]UsageRow, error)

ScanUsage scans the usage ledger.

func (*MemoryStorage) ScanValues

func (storage *MemoryStorage) ScanValues(_ context.Context, prefix StoredAddressBase) ([]StoredValue[any], error)

ScanValues returns values under a namespace-scoped key prefix.

type MemoryStorageOptions

type MemoryStorageOptions struct {
	Now func() int64
}

MemoryStorageOptions configure MemoryStorage; Now defaults to the wall clock in Unix milliseconds.

type ModelRef

type ModelRef struct {
	Provider string `json:"provider"`
	ModelID  string `json:"modelId"`
}

ModelRef identifies a provider model durably.

type MutationLine

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

MutationLine serializes complete read-modify-write jobs for one Session. Admission is synchronous and FIFO: a job admitted by Enqueue starts only after every earlier job settles, even when the earlier job failed. Seal rejects queued and future jobs while the running job drains. The zero value is ready to use.

func (*MutationLine) Enqueue

func (line *MutationLine) Enqueue(op func() (any, error)) *LineJob

Enqueue admits op behind every earlier job and returns without waiting. A sealed line rejects op with the sealing error, both at admission and when op reaches the head of the line.

func (*MutationLine) Run

func (line *MutationLine) Run(op func() (any, error)) (any, error)

Run admits op and waits for its result.

func (*MutationLine) Seal

func (line *MutationLine) Seal(err error) <-chan struct{}

Seal rejects queued and future jobs with err (the first sealing error wins) and returns a channel closed once every admitted job has settled.

type NormalizedRetryPolicy

type NormalizedRetryPolicy struct {
	MaxAttempts     int `json:"maxAttempts"`
	BaseDelayMs     int `json:"baseDelayMs"`
	MaxAgentDelayMs int `json:"maxAgentDelayMs"`
}

NormalizedRetryPolicy is the retry policy captured in operation state.

type Operation

type Operation struct {
	Meta  OperationMeta
	State OperationState
}

Operation pairs process-local meta and state; it is never stored as one object.

type OperationAt

type OperationAt string

OperationAt is the discriminator of the flat 13-leaf operation state.

const (
	AtStarting                OperationAt = "starting"
	AtCheckpoint              OperationAt = "checkpoint"
	AtAssistantReady          OperationAt = "assistant.ready"
	AtAssistantEffectPending  OperationAt = "assistant.effect_pending"
	AtAssistantRetryWait      OperationAt = "assistant.retry_wait"
	AtTools                   OperationAt = "tools"
	AtDeferredSuspended       OperationAt = "deferred.suspended"
	AtDeferredEffectPending   OperationAt = "deferred.effect_pending"
	AtSummaryDeciding         OperationAt = "summary.deciding"
	AtSummaryReady            OperationAt = "summary.ready"
	AtSummaryEffectPending    OperationAt = "summary.effect_pending"
	AtSummaryRetryWait        OperationAt = "summary.retry_wait"
	AtNavigationReadyToCommit OperationAt = "navigation.ready_to_commit"
)

func OperationAts

func OperationAts() []OperationAt

OperationAts lists every durable leaf.

type OperationError

type OperationError struct {
	Code    string     `json:"code"`
	Message string     `json:"message"`
	Details *JsonValue `json:"details,omitempty"`
}

OperationError is a machine-readable terminal failure.

func (*OperationError) UnmarshalJSON

func (operationError *OperationError) UnmarshalJSON(data []byte) error

UnmarshalJSON keeps explicit null details distinct from absent details.

type OperationIntent

type OperationIntent struct {
	Kind               string   `json:"kind"`
	PromptEntryIDs     []string `json:"promptEntryIds"`
	TargetID           *string  `json:"targetId"`
	Summarize          bool     `json:"summarize"`
	Label              *string  `json:"label,omitempty"`
	CustomInstructions *string  `json:"customInstructions,omitempty"`
}

OperationIntent is the immutable intent of one operation, discriminated by Kind: run uses PromptEntryIDs; compaction uses CustomInstructions; navigation uses TargetID (nil targets the branch root), Summarize, Label, and CustomInstructions.

func (OperationIntent) MarshalJSON

func (intent OperationIntent) MarshalJSON() ([]byte, error)

MarshalJSON emits the members of Kind.

type OperationMeta

type OperationMeta struct {
	OperationID string          `json:"operationId"`
	Lane        string          `json:"lane"`
	SourceTipID *string         `json:"sourceTipId"`
	StartedAt   int64           `json:"startedAt"`
	Intent      OperationIntent `json:"intent"`
}

OperationMeta is the immutable acceptance data of one operation.

type OperationResultRecord

type OperationResultRecord struct {
	OperationID string          `json:"operationId"`
	Kind        string          `json:"kind"`
	Status      string          `json:"status"`
	Error       *OperationError `json:"error,omitempty"`
	FromTipID   *string         `json:"fromTipId"`
	TipID       *string         `json:"tipId"`
	StartedAt   int64           `json:"startedAt"`
	EndedAt     int64           `json:"endedAt"`
}

OperationResultRecord is the immutable lane-lived observation written by one terminal transaction.

type OperationScope

type OperationScope struct {
	Control                Control     `json:"control"`
	Settings               RunSettings `json:"settings"`
	LatestAssistantEntryID *string     `json:"latestAssistantEntryId"`
}

OperationScope is the uniform scope carried by every operation leaf.

func OperationScopeOf

func OperationScopeOf(state OperationState) OperationScope

OperationScopeOf copies only the uniform scope for a successor leaf.

type OperationState

type OperationState struct {
	OperationScope
	At OperationAt `json:"at"`

	// checkpoint
	Continuation   Continuation `json:"continuation"`
	TriggerEntryID string       `json:"triggerEntryId"`

	// assistant.*, summary.*
	GenerationContext   GenerationContext `json:"generationContext"`
	NextAttempt         int               `json:"nextAttempt"`
	Attempt             int               `json:"attempt"`
	ResponseEntryID     string            `json:"responseEntryId"`
	UsageID             string            `json:"usageId"`
	IntendedOutputLimit int               `json:"intendedOutputLimit"`
	ContextWindow       int               `json:"contextWindow"`
	NotBefore           int64             `json:"notBefore"`
	ErrorMessage        string            `json:"errorMessage"`

	// tools
	Batch ToolBatch `json:"batch"`

	// deferred.*
	StepID        string                            `json:"stepId"`
	SourceEntryID string                            `json:"sourceEntryId"`
	Poll          int                               `json:"poll"`
	Configuration LaneConfiguration                 `json:"configuration"`
	StreamOptions harness.AgentHarnessStreamOptions `json:"streamOptions"`

	// summary.*
	Task           SummaryTask     `json:"task"`
	SummaryContext SummaryContext  `json:"summaryContext"`
	Request        *SummaryRequest `json:"request,omitempty"`
	UsageIDs       []string        `json:"usageIds"`

	// navigation.ready_to_commit; a nil TargetID targets the branch root.
	TargetID *string `json:"targetId"`
	Label    *string `json:"label,omitempty"`
}

OperationState is the total durable restart point of an operation: the uniform OperationScope plus the members of leaf At, listed per leaf in operationStateKeys. Members of other leaves are ignored.

func (OperationState) MarshalJSON

func (state OperationState) MarshalJSON() ([]byte, error)

MarshalJSON emits the scope and the members of leaf At.

func (*OperationState) UnmarshalJSON

func (state *OperationState) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes any leaf and rejects unknown discriminators.

type PendingEntry

type PendingEntry struct {
	Type          string
	Message       agent.AgentMessage
	CustomType    string
	CustomPayload *JsonValue
}

PendingEntry is complete content awaiting tree placement: a message payload, or a custom entry with an optional payload.

func (PendingEntry) MarshalJSON

func (entry PendingEntry) MarshalJSON() ([]byte, error)

MarshalJSON emits {type, payload} or {type, customType, payload?}.

func (*PendingEntry) UnmarshalJSON

func (entry *PendingEntry) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes either pending entry form.

type PreparedCommit

type PreparedCommit struct {
	Writes []CommittedWrite
	Result CommitResult
}

PreparedCommit is a sequenced transaction and its result without stats.

func PrepareStorageCommit

func PrepareStorageCommit(writes []Write, firstSeq, timestamp int64) (PreparedCommit, error)

PrepareStorageCommit sequences writes from firstSeq at one timestamp.

type ResolvedListReadOptions

type ResolvedListReadOptions struct {
	Cursor *ListCursor
	Order  string
	Limit  int
}

ResolvedListReadOptions are validated list read options.

func ResolveListReadOptions

func ResolveListReadOptions(options *ListReadOptions) (ResolvedListReadOptions, error)

ResolveListReadOptions validates and defaults list read options.

type ResultBoundary

type ResultBoundary struct {
	Kind        string          `json:"kind"`
	ResumeAfter *CheckpointData `json:"resumeAfter,omitempty"`
	TargetID    string          `json:"targetId"`
	Label       *string         `json:"label,omitempty"`
}

ResultBoundary is where a summary result goes: resume an enclosing run (ResumeAfter), finish standalone compaction, or commit navigation to TargetID with an optional Label.

func (ResultBoundary) MarshalJSON

func (boundary ResultBoundary) MarshalJSON() ([]byte, error)

MarshalJSON emits the members of Kind.

type RunSettings

type RunSettings struct {
	Compaction    harness.CompactionSettings `json:"compaction"`
	SteeringMode  agent.QueueMode            `json:"steeringMode"`
	FollowUpMode  agent.QueueMode            `json:"followUpMode"`
	ToolExecution string                     `json:"toolExecution"`
}

RunSettings are the harness settings captured by an operation.

type Session

type Session interface {
	SessionReader
	Metadata() SessionMetadata
	IdGenerator() IdGenerator
	GetEntry(ctx context.Context, id string) (*Entry, error)
	GetName(ctx context.Context) (*string, error)
	GetLabel(ctx context.Context, targetID string) (*string, error)
	FindEntries(ctx context.Context, query *EntryQuery) ([]Entry, error)
	FindEntry(ctx context.Context, query *EntryQuery) (*Entry, error)
	// Branch returns nil when the Branch does not exist.
	Branch(ctx context.Context, name string) (Branch, error)
	CreateBranch(ctx context.Context, name string, at *string) (Branch, error)
	BeginMutation(ctx context.Context) (SessionMutation, error)
	// Mutate runs a trusted exclusive callback over the mutation line. A public
	// Session writer called from the callback queues behind it, so waiting for
	// it deadlocks; use the supplied mutator for the callback's sole commit.
	Mutate(ctx context.Context, mutation SessionMutationCallback) (any, error)
	SetValue(ctx context.Context, address StoredAddressBase, next any) error
	DeleteValue(ctx context.Context, address StoredAddressBase) error
	AppendList(ctx context.Context, address StoredAddressBase, element any) error
	DeleteList(ctx context.Context, address StoredAddressBase) error
	// SetName deletes the name when name is nil.
	SetName(ctx context.Context, name *string) error
	// SetLabel deletes the label when label is nil.
	SetLabel(ctx context.Context, targetID string, label *string) error
	Close(ctx context.Context) error
}

Session owns global metadata, values and lists, entry and usage queries, Branch discovery and creation, one mutation line, and one backend lifecycle.

type SessionBranchExistsError

type SessionBranchExistsError struct{ Branch string }

SessionBranchExistsError reports a Branch that already exists.

func (*SessionBranchExistsError) Error

func (err *SessionBranchExistsError) Error() string

type SessionContextBuildOptions

type SessionContextBuildOptions struct {
	EntryProjectors map[string]EntryProjector
}

SessionContextBuildOptions configure BuildSessionContext.

type SessionCreateOptions

type SessionCreateOptions struct {
	ID              string
	ParentSessionID string
	Cwd             string
}

SessionCreateOptions configure repository creation; empty strings are absent. Cwd is required by file-backed repositories.

type SessionInvalidBranchError

type SessionInvalidBranchError struct {
	Branch string
	Reason string
}

SessionInvalidBranchError reports an invalid Branch name.

func (*SessionInvalidBranchError) Error

func (err *SessionInvalidBranchError) Error() string

type SessionInvariantError

type SessionInvariantError struct{ Message string }

SessionInvariantError reports inconsistent durable session state that cannot be safely advanced.

func (*SessionInvariantError) Error

func (err *SessionInvariantError) Error() string

type SessionMetadata

type SessionMetadata struct {
	ID                      string `json:"id"`
	CreatedAt               int64  `json:"createdAt"`
	StorageVersion          int    `json:"storageVersion"`
	Cwd                     string `json:"cwd,omitempty"`
	ParentSessionID         string `json:"parentSessionId,omitempty"`
	LegacyParentSessionPath string `json:"legacyParentSessionPath,omitempty"`
	Path                    string `json:"path,omitempty"`
	// ModifiedAt is the filesystem modification time in Unix milliseconds.
	ModifiedAt int64 `json:"modifiedAt,omitempty"`
}

SessionMetadata describes one stored session. The upstream per-backend metadata subtypes flatten into optional members: Cwd, Path, and ModifiedAt are populated by file-backed repositories.

type SessionMutation

type SessionMutation interface {
	SessionMutator
	// End waits for any commit attempt, invalidates the capability, and
	// releases the barrier.
	End(ctx context.Context) error
}

SessionMutation is the exclusive keyless mutation barrier of one Session. Every BeginMutation caller must call End.

type SessionMutationCallback

type SessionMutationCallback func(ctx context.Context, mutator SessionMutator) (any, error)

SessionMutationCallback runs under the Session mutation line.

type SessionMutator

type SessionMutator interface {
	SessionReader
	Commit(ctx context.Context, writes []Write) (CommitResult, error)
}

SessionMutator is the callback-scoped mutation capability: bounded reads and exactly zero or one commit attempt.

type SessionPendingAssistantMessageError

type SessionPendingAssistantMessageError struct{}

SessionPendingAssistantMessageError rejects persisting a pending assistant message.

func (*SessionPendingAssistantMessageError) Error

type SessionReader

type SessionReader interface {
	GetEntries(ctx context.Context, ids []string) (map[string]Entry, error)
	GetStats(ctx context.Context) (SessionStats, error)
	GetValue(ctx context.Context, address StoredAddressBase) (*StoredValue[any], error)
	ScanValues(ctx context.Context, prefix StoredAddressBase) ([]StoredValue[any], error)
	ReadList(ctx context.Context, address StoredAddressBase, options *ListReadOptions) ([]ListElement[any], error)
	// ScanBranch scans from an explicit entry while the capability is valid.
	ScanBranch(ctx context.Context, query StorageBranchScan) ([]Entry, error)
}

SessionReader is the bounded read surface of a Session and of mutation capabilities. Use GetValue, ScanValues, and ReadList for typed reads.

type SessionStats

type SessionStats struct {
	MessageCount int      `json:"messageCount"`
	Usage        ai.Usage `json:"usage"`
}

SessionStats are the maintained message-count and ledger totals.

type SessionUnknownTargetError

type SessionUnknownTargetError struct{ TargetID string }

SessionUnknownTargetError reports an absent target entry.

func (*SessionUnknownTargetError) Error

func (err *SessionUnknownTargetError) Error() string

type SettledAssistantMessage

type SettledAssistantMessage = agent.AssistantMessage

SettledAssistantMessage is an assistant message whose stopReason is not "pending"; session writes reject pending assistant messages.

type Storage

type Storage interface {
	Commit(ctx context.Context, writes []Write) (CommitResult, error)
	GetEntries(ctx context.Context, ids []string) (map[string]Entry, error)
	GetValue(ctx context.Context, address StoredAddressBase) (*StoredValue[any], error)
	ScanValues(ctx context.Context, prefix StoredAddressBase) ([]StoredValue[any], error)
	ReadList(ctx context.Context, address StoredAddressBase, options *ListReadOptions) ([]ListElement[any], error)
	ScanBranch(ctx context.Context, query StorageBranchScan) ([]Entry, error)
	ScanBranchStructure(ctx context.Context, query StorageBranchScan) ([]EntryStructure, error)
	ScanEntries(ctx context.Context, query EntryScan) ([]Entry, error)
	ScanUsage(ctx context.Context, query UsageScan) ([]UsageRow, error)
	GetStats(ctx context.Context) (SessionStats, error)
	Close(ctx context.Context) error
}

Storage is the durable backend of one session.

type StorageBackedSession

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

StorageBackedSession is the typed Session boundary shared by concrete session repositories.

func NewStorageBackedSession

func NewStorageBackedSession(metadata SessionMetadata, storage Storage, options *StorageBackedSessionOptions) *StorageBackedSession

NewStorageBackedSession binds a session to its storage.

func (*StorageBackedSession) AppendList

func (session *StorageBackedSession) AppendList(ctx context.Context, address StoredAddressBase, element any) error

AppendList appends one list element in its own commit.

func (*StorageBackedSession) AppendToBranch

func (session *StorageBackedSession) AppendToBranch(ctx context.Context, name string, entry Entry) (string, error)

AppendToBranch inserts a message or custom entry at a Branch tip and moves the tip in one mutation. Only Type, Message, CustomType, and Data are read.

func (*StorageBackedSession) BeginMutation

func (session *StorageBackedSession) BeginMutation(context.Context) (SessionMutation, error)

BeginMutation waits for the Session barrier and returns its capability.

func (*StorageBackedSession) Branch

func (session *StorageBackedSession) Branch(ctx context.Context, name string) (Branch, error)

Branch returns an existing Branch, or nil.

func (*StorageBackedSession) Close

func (session *StorageBackedSession) Close(ctx context.Context) error

Close seals the mutation line, drains admitted mutations, and closes the storage; it is idempotent.

func (*StorageBackedSession) CreateBranch

func (session *StorageBackedSession) CreateBranch(ctx context.Context, name string, at *string) (Branch, error)

CreateBranch atomically validates the name, absence, and a non-null target, then writes only the tip.

func (*StorageBackedSession) DeleteList

func (session *StorageBackedSession) DeleteList(ctx context.Context, address StoredAddressBase) error

DeleteList deletes a whole list in its own commit.

func (*StorageBackedSession) DeleteValue

func (session *StorageBackedSession) DeleteValue(ctx context.Context, address StoredAddressBase) error

DeleteValue deletes one value in its own commit.

func (*StorageBackedSession) FindEntries

func (session *StorageBackedSession) FindEntries(ctx context.Context, query *EntryQuery) ([]Entry, error)

FindEntries queries session-wide entries.

func (*StorageBackedSession) FindEntry

func (session *StorageBackedSession) FindEntry(ctx context.Context, query *EntryQuery) (*Entry, error)

FindEntry returns the first matching entry, or nil.

func (*StorageBackedSession) GetBranchTip

func (session *StorageBackedSession) GetBranchTip(ctx context.Context, name string) (*string, error)

GetBranchTip returns a Branch's tip; an absent Branch is an invariant error.

func (*StorageBackedSession) GetEntries

func (session *StorageBackedSession) GetEntries(ctx context.Context, ids []string) (map[string]Entry, error)

GetEntries returns the requested existing entries by id.

func (*StorageBackedSession) GetEntry

func (session *StorageBackedSession) GetEntry(ctx context.Context, id string) (*Entry, error)

GetEntry returns one entry, or nil.

func (*StorageBackedSession) GetLabel

func (session *StorageBackedSession) GetLabel(ctx context.Context, targetID string) (*string, error)

GetLabel returns an entry label, or nil.

func (*StorageBackedSession) GetName

func (session *StorageBackedSession) GetName(ctx context.Context) (*string, error)

GetName returns the session name, or nil.

func (*StorageBackedSession) GetStats

func (session *StorageBackedSession) GetStats(ctx context.Context) (SessionStats, error)

GetStats returns the maintained totals.

func (*StorageBackedSession) GetValue

func (session *StorageBackedSession) GetValue(ctx context.Context, address StoredAddressBase) (*StoredValue[any], error)

GetValue reads one erased value.

func (*StorageBackedSession) IdGenerator

func (session *StorageBackedSession) IdGenerator() IdGenerator

IdGenerator returns the session id generator.

func (*StorageBackedSession) Metadata

func (session *StorageBackedSession) Metadata() SessionMetadata

Metadata returns the session metadata.

func (*StorageBackedSession) Mutate

func (session *StorageBackedSession) Mutate(ctx context.Context, mutation SessionMutationCallback) (any, error)

Mutate runs mutation under the barrier and always ends it.

func (*StorageBackedSession) ReadList

func (session *StorageBackedSession) ReadList(ctx context.Context, address StoredAddressBase, options *ListReadOptions) ([]ListElement[any], error)

ReadList reads one erased list page.

func (*StorageBackedSession) ScanBranch

func (session *StorageBackedSession) ScanBranch(ctx context.Context, query StorageBranchScan) ([]Entry, error)

ScanBranch scans a branch path from an explicit entry.

func (*StorageBackedSession) ScanValues

func (session *StorageBackedSession) ScanValues(ctx context.Context, prefix StoredAddressBase) ([]StoredValue[any], error)

ScanValues reads erased values under a namespace-scoped prefix.

func (*StorageBackedSession) SetLabel

func (session *StorageBackedSession) SetLabel(ctx context.Context, targetID string, label *string) error

SetLabel sets or, for nil, deletes an entry label.

func (*StorageBackedSession) SetName

func (session *StorageBackedSession) SetName(ctx context.Context, name *string) error

SetName sets or, for nil, deletes the session name.

func (*StorageBackedSession) SetValue

func (session *StorageBackedSession) SetValue(ctx context.Context, address StoredAddressBase, next any) error

SetValue replaces one value in its own commit.

type StorageBackedSessionOptions

type StorageBackedSessionOptions struct {
	MutationLine *MutationLine
	IdGenerator  IdGenerator
	OnClose      func()
}

StorageBackedSessionOptions configure a StorageBackedSession.

type StorageBranchScan

type StorageBranchScan struct {
	Start      string
	StopAtType EntryType
	StopAtID   string
	Type       EntryType
	CustomType string
	Order      string
	Limit      *int
	Cursor     *EntryCursor
}

StorageBranchScan is a BranchScan with a required start.

type StoredAddressBase

type StoredAddressBase struct {
	Namespace string `json:"namespace"`
	Key       string `json:"key"`
	Kind      string `json:"kind"`
}

StoredAddressBase is the erased (namespace, key, kind) of one durable location. Equal triples name the same location.

type StoredValue

type StoredValue[T any] struct {
	Address Value[T] `json:"address"`
	Value   T        `json:"value"`
	Seq     int64    `json:"seq"`
}

StoredValue is a current value and the sequence of its last set.

func GetValue

func GetValue[T any](ctx context.Context, reader SessionReader, address Value[T]) (*StoredValue[T], error)

GetValue reads one typed value from a reader; nil means absent.

func ScanValues

func ScanValues[T any](ctx context.Context, reader SessionReader, prefix Value[T]) ([]StoredValue[T], error)

ScanValues reads the typed values under a namespace-scoped key prefix, in key-ascending order.

type SummaryContext

type SummaryContext struct {
	ResultEntryID string                            `json:"resultEntryId"`
	Configuration LaneConfiguration                 `json:"configuration"`
	StreamOptions harness.AgentHarnessStreamOptions `json:"streamOptions"`
	RetryPolicy   NormalizedRetryPolicy             `json:"retryPolicy"`
}

SummaryContext is the structural request snapshot of one summary task.

type SummaryRequest

type SummaryRequest struct {
	Index   int    `json:"index"`
	UsageID string `json:"usageId"`
}

SummaryRequest identifies one nested structural provider request.

type SummaryTask

type SummaryTask struct {
	TaskID             string         `json:"taskId"`
	Reason             string         `json:"reason,omitempty"`
	CustomInstructions *string        `json:"customInstructions,omitempty"`
	Boundary           ResultBoundary `json:"boundary"`
}

SummaryTask is the structural task shared by the summary.* leaves.

type ToolBatch

type ToolBatch struct {
	AssistantEntryID string            `json:"assistantEntryId"`
	Configuration    LaneConfiguration `json:"configuration"`
	TurnID           string            `json:"turnId"`
	Calls            []ToolCall        `json:"calls"`
}

ToolBatch is the nested tool-call state machine of one assistant response.

type ToolCall

type ToolCall struct {
	Status        string `json:"status"`
	SourceIndex   int    `json:"sourceIndex"`
	ResultEntryID string `json:"resultEntryId"`
	Replay        string `json:"replay"`
	Terminate     bool   `json:"terminate"`
}

ToolCall tracks one call of a tool batch by its zero-based index in the assistant message's complete content array. Replay applies to effect_pending; Terminate to outcome_ready and completed.

func (ToolCall) MarshalJSON

func (call ToolCall) MarshalJSON() ([]byte, error)

MarshalJSON emits the members of Status.

type UsageRow

type UsageRow struct {
	ID    string   `json:"id"`
	Seq   int64    `json:"seq"`
	Usage ai.Usage `json:"usage"`
	// EntryID names the entry the cost belongs to, when there is one.
	EntryID *string `json:"entryId,omitempty"`
	// Adjustment marks a caller-supplied reconciliation row.
	Adjustment bool       `json:"adjustment"`
	Details    *JsonValue `json:"details,omitempty"`
}

UsageRow is one append-only cost ledger row.

func (*UsageRow) UnmarshalJSON

func (row *UsageRow) UnmarshalJSON(data []byte) error

UnmarshalJSON keeps explicit null details distinct from absent details.

type UsageScan

type UsageScan struct {
	FromSeq *int64
	ToSeq   *int64
	Order   string
	Limit   *int
}

UsageScan queries the usage ledger.

type UsageWrite

type UsageWrite struct{ Row UsageRow }

UsageWrite inserts one ledger row; storage assigns its seq.

func InsertUsage

func InsertUsage(row UsageRow) UsageWrite

InsertUsage constructs a ledger insert write; storage assigns the seq.

func (UsageWrite) MarshalJSON

func (write UsageWrite) MarshalJSON() ([]byte, error)

MarshalJSON emits {kind: "usage", row} without the unassigned seq.

type Value

type Value[T any] struct {
	StoredAddressBase
}

Value is a bound typed address of one replaceable durable value.

func BranchTip

func BranchTip(branch string) Value[*string]

BranchTip addresses the tip of one Branch; nil is the empty root tip.

func BranchTipInventoryPrefix

func BranchTipInventoryPrefix() Value[*string]

BranchTipInventoryPrefix scans every Branch tip.

func EntryLabel

func EntryLabel(entryID string) Value[string]

EntryLabel addresses one entry label.

func LaneConfig

func LaneConfig(lane string) Value[LaneConfiguration]

LaneConfig addresses one lane's total configuration.

func LaneStateValue

func LaneStateValue(lane string) Value[LaneState]

LaneStateValue addresses one lane's state (upstream laneState; renamed because Go types and functions share one namespace).

func MustValue

func MustValue[T any](namespace, key string) Value[T]

MustValue binds a scalar address and panics on an invalid component, like the upstream constructor's TypeError for a trusted-programming defect.

func NewValue

func NewValue[T any](namespace, key string) (Value[T], error)

NewValue binds a scalar address (upstream value<T>(namespace, key)).

func OperationMetaValue

func OperationMetaValue(operationID string) Value[OperationMeta]

OperationMetaValue addresses one operation's metadata (upstream operationMeta).

func OperationPreparation

func OperationPreparation(operationID, taskID string) Value[DurableStructuralPreparation]

OperationPreparation addresses one structural preparation.

func OperationPreparationPrefix

func OperationPreparationPrefix(operationID string) Value[DurableStructuralPreparation]

OperationPreparationPrefix scans an operation's preparations.

func OperationResult

func OperationResult(operationID string) Value[OperationResultRecord]

OperationResult addresses one immutable terminal record.

func OperationStateValue

func OperationStateValue(operationID string) Value[OperationState]

OperationStateValue addresses one operation's state (upstream operationState).

func OperationToolArgs

func OperationToolArgs(operationID, stepID string, sourceIndex int) Value[map[string]JsonValue]

OperationToolArgs addresses one call's effective arguments.

func OperationToolArgsPrefix

func OperationToolArgsPrefix(operationID string, stepID *string) Value[map[string]JsonValue]

OperationToolArgsPrefix scans an operation's (or one step's) tool arguments; nil stepID is absent.

func OperationToolMemo

func OperationToolMemo(operationID, invocationID, name string) Value[JsonValue]

OperationToolMemo addresses one invocation-scoped memo.

func OperationToolMemoPrefix

func OperationToolMemoPrefix(operationID string, invocationID *string) Value[JsonValue]

OperationToolMemoPrefix scans an operation's (or one invocation's) memos; nil invocationID is absent.

func PendingEntryValue

func PendingEntryValue(entryID string) Value[PendingEntry]

PendingEntryValue addresses content awaiting placement (upstream pendingEntry).

func PendingToolOutput

func PendingToolOutput(operationID, invocationID string) Value[harness.AgentToolResult]

PendingToolOutput addresses one invocation's latest progress checkpoint.

func PendingToolOutputPrefix

func PendingToolOutputPrefix(operationID string) Value[harness.AgentToolResult]

PendingToolOutputPrefix scans an operation's tool checkpoints.

func (Value[T]) Address

func (address Value[T]) Address() StoredAddressBase

Address returns the erased address.

type ValueDeleteWrite

type ValueDeleteWrite struct{ Namespace, Key string }

ValueDeleteWrite deletes one scalar value; deleting an absent value is a no-op.

func DeleteValue

func DeleteValue[T any](address Value[T]) ValueDeleteWrite

DeleteValue constructs a scalar delete write.

func (ValueDeleteWrite) MarshalJSON

func (write ValueDeleteWrite) MarshalJSON() ([]byte, error)

MarshalJSON emits {kind: "value", op: "delete", namespace, key}.

type ValueList

type ValueList[T any] struct {
	StoredAddressBase
}

ValueList is a bound typed address of one append-only durable list.

func MustList

func MustList[T any](namespace, key string) ValueList[T]

MustList binds a list address and panics on an invalid component.

func NewList

func NewList[T any](namespace, key string) (ValueList[T], error)

NewList binds a list address (upstream list<T>(namespace, key)).

func PendingAssistantFrames

func PendingAssistantFrames(operationID, responseEntryID string) ValueList[ai.AssistantMessageFrame]

PendingAssistantFrames addresses one response's committed frame prefix.

func (ValueList[T]) Address

func (address ValueList[T]) Address() StoredAddressBase

Address returns the erased address.

type ValueSetWrite

type ValueSetWrite struct {
	Namespace string
	Key       string
	Value     any
}

ValueSetWrite replaces one scalar value.

func SetValue

func SetValue[T any](address Value[T], next T) ValueSetWrite

SetValue constructs a scalar set write whose value type is fixed by address.

func (ValueSetWrite) MarshalJSON

func (write ValueSetWrite) MarshalJSON() ([]byte, error)

MarshalJSON emits {kind: "value", op: "set", namespace, key, value}.

type Write

type Write interface {
	// contains filtered or unexported methods
}

Write is one erased transaction write: EntryWrite, UsageWrite, ValueSetWrite, ValueDeleteWrite, ListAppendWrite, or ListDeleteWrite.

Directories

Path Synopsis
Package sessiontesting holds runner-independent session test fixtures and storage decorators shared by every backend's conformance and benchmarks.
Package sessiontesting holds runner-independent session test fixtures and storage decorators shared by every backend's conformance and benchmarks.
benchmark
Package benchmark holds the deterministic session workloads shared by every backend's storage and repository benchmarks.
Package benchmark holds the deterministic session workloads shared by every backend's storage and repository benchmarks.
conformance
Package conformance holds the runner-independent Storage and SessionRepo conformance suites every session backend must pass.
Package conformance holds the runner-independent Storage and SessionRepo conformance suites every session backend must pass.

Jump to

Keyboard shortcuts

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