Documentation
¶
Overview ¶
Package session adds coding-application identity and single-writer ownership to the durable Harness session repository.
Index ¶
- Constants
- Variables
- func CollectMediaReferences(ctx context.Context, sessionDir string) (map[string]struct{}, error)
- func CopySessionMedia(ctx context.Context, sourceDir string, destinationDir string, ...) error
- func DefaultLegacyWorkspaceRegistryPath(storeRoot string) string
- func IdleSince(sessionDir string) (time.Time, bool)
- func LegacyStoreDetected(root string) bool
- func MediaReferencesFromEntries(entries []harness.Entry) map[string]struct{}
- func MediaRelativePath(dir, name string) (string, error)
- func UpdateMetadataRecord(path string, mutate func(*MetadataRecord) error) error
- func ValidMediaReference(path, digest string) bool
- func ValidateArchiveID(id string) error
- func ValidateID(id string) error
- func ValidateMetadataRecord(record MetadataRecord) error
- func WriteMetadataRecord(path string, record MetadataRecord) error
- func WriteSearchDoc(path string, doc SearchDoc) error
- type ArchiveInfo
- type ArchiveLine
- type ArchiveListPage
- type ArchiveListRequest
- type ArchiveMatch
- type ArchiveReadPage
- type ArchiveReadRequest
- type ArchiveReader
- func (r *ArchiveReader) List(ctx context.Context, request ArchiveListRequest) (ArchiveListPage, error)
- func (r *ArchiveReader) Read(ctx context.Context, request ArchiveReadRequest) (ArchiveReadPage, error)
- func (r *ArchiveReader) Search(ctx context.Context, request ArchiveSearchRequest) (ArchiveSearchPage, error)
- type ArchiveSearchCursor
- type ArchiveSearchPage
- type ArchiveSearchRequest
- type ArchiveSegmentInfo
- type ArchiveSource
- type ArchiveStore
- type ChildIndexEntry
- type ChildIndexState
- type Counts
- type CreateOptions
- type ForkOptions
- type ForkSubagentOptions
- type FormatInfo
- type GCReport
- type GitRef
- type Group
- type Handle
- type Journal
- type JournalRecord
- type Kind
- type LegacyWorkspaceRegistry
- type LockedError
- type MediaRef
- type MediaStore
- func (m *MediaStore) CopyTo(ctx context.Context, destination *MediaStore, refs map[string]struct{}) error
- func (m *MediaStore) Dir() string
- func (m *MediaStore) Enumerate(ctx context.Context) ([]MediaRef, error)
- func (m *MediaStore) GC(ctx context.Context, refs map[string]struct{}, grace time.Duration, ...) (GCReport, error)
- func (m *MediaStore) Open(ctx context.Context, ref MediaRef) ([]byte, error)
- func (m *MediaStore) PutModelCopy(ctx context.Context, original MediaRef, mimeType string, data []byte) (MediaRef, error)
- func (m *MediaStore) PutOriginal(ctx context.Context, mimeType string, data []byte) (MediaRef, error)
- func (m *MediaStore) WriteRef(ctx context.Context, ref MediaRef, data []byte) error
- type Metadata
- type MetadataListing
- type MetadataRecord
- type MigrateOptions
- type MigrateReport
- type MigratedSession
- type ModelSnapshot
- type OpenOptions
- type OpenTeamWorkerOptions
- type ParentRef
- type Repository
- func (r *Repository) Archives(handle *Handle) (*ArchiveStore, error)
- func (r *Repository) CopyArchives(ctx context.Context, source *Handle, destinationID string, ids []string) error
- func (r *Repository) Create(ctx context.Context, options CreateOptions) (*Handle, error)
- func (r *Repository) Delete(ctx context.Context, id string) (resultErr error)
- func (r *Repository) Dir() string
- func (r *Repository) Fork(ctx context.Context, source *Handle, options ForkOptions) (*Handle, error)
- func (r *Repository) ForkSubagent(ctx context.Context, source *Handle, options ForkSubagentOptions) (*Handle, error)
- func (r *Repository) Layout() StoreLayout
- func (r *Repository) List(ctx context.Context) ([]Metadata, error)
- func (r *Repository) ListMetadata(ctx context.Context) (MetadataListing, error)
- func (r *Repository) ListSubagents(ctx context.Context, parent Metadata) ([]Metadata, error)
- func (r *Repository) ListTeamWorkers(ctx context.Context, parentSessionID string, teamID team.ID, limit int) ([]Metadata, error)
- func (r *Repository) Open(ctx context.Context, options OpenOptions) (*Handle, error)
- func (r *Repository) OpenTeamWorker(ctx context.Context, options OpenTeamWorkerOptions) (*Handle, error)
- func (r *Repository) PruneMedia(ctx context.Context, id string, age time.Duration, dryRun bool) (GCReport, error)
- func (r *Repository) UpdateChildIndexState(child Metadata, state ChildIndexState, at time.Time) error
- type SearchDoc
- type SkippedSession
- type StagedArchive
- type StateStore
- func (s *StateStore) AppendJSONL(name string, values ...any) error
- func (s *StateStore) Dir() string
- func (s *StateStore) ReadJSON(name string, target any) (bool, error)
- func (s *StateStore) ReadJSONL(name string, limit int) ([][]byte, error)
- func (s *StateStore) Remove(name string) error
- func (s *StateStore) WriteJSON(name string, value any) error
- type StoreLayout
- func (l StoreLayout) ArchiveDir(workspacePath, id string) string
- func (l StoreLayout) ArchiveRelDir(workspacePath, id string) []string
- func (l StoreLayout) AssetsDir(workspacePath, id string) string
- func (l StoreLayout) ChildIndexEntryDir(workspacePath, parentID, childID string) string
- func (l StoreLayout) ChildIndexEntryFile(workspacePath, parentID, childID string) string
- func (l StoreLayout) CompactionDir(workspacePath, id string) string
- func (l StoreLayout) GroupDir(workspacePath string) string
- func (l StoreLayout) GroupKey(workspacePath string) (key string, fallback bool, err error)
- func (l StoreLayout) ImagesDir(workspacePath, id string) string
- func (l StoreLayout) JournalFile(workspacePath, id string) string
- func (l StoreLayout) LockFile(workspacePath, id string) string
- func (l StoreLayout) MetadataFile(workspacePath, id string) string
- func (l StoreLayout) ModelDir(workspacePath, id string) string
- func (l StoreLayout) Root() string
- func (l StoreLayout) SearchFile(workspacePath, id string) string
- func (l StoreLayout) SessionDir(workspacePath, id string) string
- func (l StoreLayout) SessionRelDir(workspacePath, id string) []string
- func (l StoreLayout) StateDir(workspacePath, id string) string
- func (l StoreLayout) SubagentIndexFile(workspacePath, id string) string
- func (l StoreLayout) SubagentsDir(workspacePath, id string) string
- func (l StoreLayout) TerminalDir(workspacePath, id string) string
- func (l StoreLayout) TranscriptFile(workspacePath, id string) string
- type StoreRoot
- type SubagentIdentity
- type SubagentRef
- type TeamWorkerLineage
- type TeamWorkerRef
- type TitleRecord
- type WorkspaceRecord
- type WorkspaceRef
Constants ¶
const ( ArchiveMaxTranscriptBytes = 128 << 20 ArchiveMaxRecordBytes = 16 << 20 ArchiveMaxRecords = 100_000 ArchiveMaxRenderedBytes = 128 << 20 ArchiveMaxSegments = 1024 ArchiveMaxReferences = 1024 ArchiveMaxOutputBytes = 64 << 10 )
Archive limits are independent of model request and tool output budgets.
const ( // JournalVersion is the event journal format version. JournalVersion = 1 // JournalSchema names the event journal record envelope. JournalSchema = "pips.coding.session.journal/v1" )
Journal format bounds. One record is a self-contained JSON line.
const ( // StoreSchema names the on-disk session store format. StoreSchema = "pips.coding.session/v2" // StoreVersion is the numeric store format version. StoreVersion = 2 // MetadataFileName is the session index record inside a session directory. MetadataFileName = "session.json" // TranscriptFileName is the authoritative conversation tree. TranscriptFileName = "transcript.jsonl" // JournalFileName is the authoritative coding event journal. JournalFileName = "events.jsonl" // SearchFileName is the derived, rebuildable search document. SearchFileName = "search.json" // WorkspaceFileName records a group's original workspace path. WorkspaceFileName = "workspace.json" // LockFileName is the single-writer advisory lock inside a session directory. LockFileName = "session.lock" // ModelDirName holds model-input snapshots. ModelDirName = "model" // StateDirName holds derived, rebuildable state sidecars. StateDirName = "state" // ArchiveDirName holds content-addressed archive objects. ArchiveDirName = "archives" // CompactionDirName holds compaction checkpoints. CompactionDirName = "compaction" // SubagentsDirName holds the parent-side child index. SubagentsDirName = "subagents" // SubagentIndexFileName is the child index's completeness marker. SubagentIndexFileName = "index.json" // ChildIndexEntryFileName is one child's record inside the parent's index. ChildIndexEntryFileName = "entry.json" // TerminalDirName holds bounded tool output logs. TerminalDirName = "terminal" // ImagesDirName holds session media originals (clipboard, Workspace, ACP, // and future generated media). ImagesDirName = "images" // AssetsDirName holds the bounded model-ready copies of session media. AssetsDirName = "assets" // UnknownWorkspaceKey groups sessions whose workspace path is unknown. UnknownWorkspaceKey = "_unknown" )
Session store v2 layout. One session is one directory under a workspace group; every durable artifact of that session lives inside it.
const ( // MaxSearchPrompts caps how many user prompts one document retains. MaxSearchPrompts = 32 // MaxSearchPromptBytes caps the length of one retained prompt. MaxSearchPromptBytes = 512 // MaxSearchContentBytes caps the combined size of all retained prompts. MaxSearchContentBytes = 8 << 10 )
Search document bounds. A document is a bounded projection of one session so a search pass never has to open a transcript.
const ( // SystemPromptFileName is the rendered system prompt sent to the model. SystemPromptFileName = "system_prompt.txt" // PromptContextFileName holds the inputs the system prompt was rendered from. PromptContextFileName = "prompt_context.json" // ToolDefinitionsFileName holds the function tools sent on the latest call. ToolDefinitionsFileName = "tool_definitions.json" )
Model snapshot file names. The model directory records exactly what was sent to the model and the inputs it was rendered from; it is audit material and is never consulted to rebuild the conversation.
const LegacyWorkspaceFile = "workspaces.json"
LegacyWorkspaceFile is the pre-v2 workspace registry that sits beside the session store root.
const SearchSchema = "pips.coding.session.search/v1"
SearchSchema names the derived search document format.
Variables ¶
var ( // ErrArchiveInvalid identifies invalid input or unsafe file ownership/modes. ErrArchiveInvalid = errors.New("session archive: invalid input") // ErrArchiveLimit identifies an encoded, rendered or operation bound violation. ErrArchiveLimit = errors.New("session archive: limit exceeded") // ErrArchiveCorrupt identifies failed integrity or format validation. ErrArchiveCorrupt = errors.New("session archive: corrupt object") // ErrArchiveDenied identifies a reference absent from the bound allowlist. ErrArchiveDenied = errors.New("session archive: reference not authorized") // ErrArchiveNotFound identifies an absent object in the owning session. ErrArchiveNotFound = errors.New("session archive: object not found") // ErrArchiveIO identifies a storage operation failure; its cause is preserved. ErrArchiveIO = errors.New("session archive: storage failure") // ErrArchivePublicationUncertain means the final name exists but its directory // sync failed. Never remove that object or append a checkpoint on this error. ErrArchivePublicationUncertain = errors.New("session archive: publication durability uncertain") )
var ( // ErrMediaInvalid means a media reference, path, or file name is unusable. ErrMediaInvalid = errors.New("coding session: invalid media reference") // ErrMediaMissing means a referenced media file does not exist. ErrMediaMissing = errors.New("coding session: media file missing") // ErrMediaCorrupt means a media file's bytes do not match its reference. ErrMediaCorrupt = errors.New("coding session: media digest mismatch") // ErrMediaLimit means a media file exceeds the bounded read limit. ErrMediaLimit = errors.New("coding session: media exceeds the read limit") )
Media store errors.
var ( // ErrInvalid means repository, session, or metadata input is invalid. ErrInvalid = errors.New("coding session: invalid input") // ErrLocked means another writer currently owns the requested session. ErrLocked = errors.New("coding session: session is locked") // ErrWorkspaceMismatch means a stored session belongs to another workspace // identity. ErrWorkspaceMismatch = errors.New("coding session: workspace mismatch") // ErrLineageMismatch means a Team Worker session is not owned by the exact // Team resource lineage supplied by its caller. ErrLineageMismatch = errors.New("coding session: Team Worker lineage mismatch") // ErrUnsupportedPlatform means this platform cannot enforce the P0 // single-writer lock contract. ErrUnsupportedPlatform = errors.New("coding session: unsupported platform") )
var ErrChildIndex = errors.New("coding session: invalid child index")
ErrChildIndex identifies an unreadable or unsupported parent-side child index record.
var ErrJournalCorrupt = errors.New("coding session: corrupt event journal")
ErrJournalCorrupt identifies a journal whose interior is unreadable. A trailing partial line is tolerated and never produces this error.
var ErrLayout = errors.New("coding session: invalid store layout")
ErrLayout identifies an unusable session store layout input.
var ErrMetadata = errors.New("coding session: invalid metadata")
ErrMetadata identifies an unreadable or unsupported session metadata record.
var ErrSearch = errors.New("coding session: invalid search document")
ErrSearch identifies an invalid or unreadable search document.
var ErrSnapshot = errors.New("coding session: invalid model snapshot")
ErrSnapshot identifies an invalid model snapshot request or payload.
var ErrState = errors.New("coding session: invalid state sidecar")
ErrState identifies an invalid state sidecar request or payload.
Functions ¶
func CollectMediaReferences ¶ added in v0.1.9
CollectMediaReferences returns every session-relative media path the session's transcript and archives name. A missing transcript or archive directory is empty, not an error; a corrupt artifact is an error.
func CopySessionMedia ¶ added in v0.1.9
func CopySessionMedia( ctx context.Context, sourceDir string, destinationDir string, entries []harness.Entry, ) error
CopySessionMedia copies the media the retained fork entries reference from one session directory into another.
func DefaultLegacyWorkspaceRegistryPath ¶ added in v0.1.9
DefaultLegacyWorkspaceRegistryPath returns the registry beside a session store root, which is where the pre-v2 layout kept it.
func IdleSince ¶ added in v0.1.9
IdleSince returns the newest modification time among the session's top-level artifacts, or the zero time when nothing is readable. It is the TTL input for `pips session gc`.
func LegacyStoreDetected ¶ added in v0.1.9
LegacyStoreDetected reports whether root still holds pre-v2 session files.
func MediaReferencesFromEntries ¶ added in v0.1.9
MediaReferencesFromEntries collects the session-relative media paths every message in entries references, including nested tool-result content.
func MediaRelativePath ¶ added in v0.1.9
MediaRelativePath joins a media directory and file name into a session-relative path and validates the result.
func UpdateMetadataRecord ¶ added in v0.1.9
func UpdateMetadataRecord(path string, mutate func(*MetadataRecord) error) error
UpdateMetadataRecord reads, mutates, and rewrites one session.json. A failed mutation leaves the stored record untouched.
func ValidMediaReference ¶ added in v0.1.9
ValidMediaReference reports whether path is a session-relative media path (one media directory plus one content-addressed file name) and digest is a lowercase hex SHA-256.
func ValidateArchiveID ¶ added in v0.1.5
ValidateArchiveID accepts only a lowercase SHA-256 content identity.
func ValidateID ¶
ValidateID verifies that id is safe to use as a durable session name.
func ValidateMetadataRecord ¶ added in v0.1.9
func ValidateMetadataRecord(record MetadataRecord) error
ValidateMetadataRecord rejects a record this build cannot honor.
func WriteMetadataRecord ¶ added in v0.1.9
func WriteMetadataRecord(path string, record MetadataRecord) error
WriteMetadataRecord atomically publishes one validated session.json.
func WriteSearchDoc ¶ added in v0.1.9
WriteSearchDoc validates and atomically publishes one search document.
Types ¶
type ArchiveInfo ¶ added in v0.1.5
type ArchiveInfo struct {
ID string `json:"id"`
Source ArchiveSource `json:"source"`
Records int `json:"records"`
TranscriptBytes int64 `json:"transcript_bytes"`
RenderedBytes int64 `json:"rendered_bytes"`
Segments int `json:"segments"`
}
ArchiveInfo contains bounded discovery metadata, not archived content.
type ArchiveLine ¶ added in v0.1.5
ArchiveLine numbers are one-based within the selected text segment.
type ArchiveListPage ¶ added in v0.1.5
type ArchiveListPage struct {
Archives []ArchiveInfo `json:"archives,omitempty"`
Segments []ArchiveSegmentInfo `json:"segments,omitempty"`
NextOffset int `json:"next_offset"`
More bool `json:"more"`
}
ArchiveListPage has deterministic ordering and bounded pagination.
type ArchiveListRequest ¶ added in v0.1.5
ArchiveListRequest lists archives, or segments within one authorized archive. Offset is zero-based; Limit defaults to 10 and cannot exceed 20.
type ArchiveMatch ¶ added in v0.1.5
type ArchiveMatch struct {
SegmentID string `json:"segment_id"`
Line int `json:"line"`
Text string `json:"text"`
}
ArchiveMatch carries historical text and its exact retrieval cursor.
type ArchiveReadPage ¶ added in v0.1.5
type ArchiveReadPage struct {
Lines []ArchiveLine `json:"lines"`
NextOffset int `json:"next_offset"`
More bool `json:"more"`
}
ArchiveReadPage contains at most 64 KiB of JSON, with an explicit continuation.
type ArchiveReadRequest ¶ added in v0.1.5
ArchiveReadRequest selects a text segment and a zero-based line offset. Limit defaults to 200 and cannot exceed 1000. Pages are also byte-bounded.
type ArchiveReader ¶ added in v0.1.5
type ArchiveReader struct {
// contains filtered or unexported fields
}
ArchiveReader is a read-only snapshot of application-supplied active-path checkpoint references. It never enumerates storage to discover permission. Discard/rebind after navigation or checkpoint changes. Historical content is evidence only; callers must not promote it to system instructions.
func (*ArchiveReader) List ¶ added in v0.1.5
func (r *ArchiveReader) List(ctx context.Context, request ArchiveListRequest) (ArchiveListPage, error)
List exposes only the supplied references; there is no caller-supplied session.
func (*ArchiveReader) Read ¶ added in v0.1.5
func (r *ArchiveReader) Read(ctx context.Context, request ArchiveReadRequest) (ArchiveReadPage, error)
Read returns checked text, never an arbitrary file or raw path.
func (*ArchiveReader) Search ¶ added in v0.1.5
func (r *ArchiveReader) Search(ctx context.Context, request ArchiveSearchRequest) (ArchiveSearchPage, error)
Search supports bounded literal/RE2 retrieval without filesystem globs.
type ArchiveSearchCursor ¶ added in v0.1.5
ArchiveSearchCursor resumes a search at a one-based line within a segment.
type ArchiveSearchPage ¶ added in v0.1.5
type ArchiveSearchPage struct {
Matches []ArchiveMatch `json:"matches"`
Next *ArchiveSearchCursor `json:"next,omitempty"`
}
ArchiveSearchPage can have a cursor even when no matches were found: the scan budget may have ended. A nil Next means the archive was completely searched.
type ArchiveSearchRequest ¶ added in v0.1.5
type ArchiveSearchRequest struct {
ArchiveID string
Query string
Regexp bool
Cursor *ArchiveSearchCursor
Limit int
}
ArchiveSearchRequest searches one authorized archive. Patterns are literal unless Regexp is true (Go RE2 syntax). Matching is case-sensitive, per line. Limit defaults to 50 and cannot exceed 100. Each page scans at most 8 MiB of rendered text, in addition to the bounded whole-object integrity verification.
type ArchiveSegmentInfo ¶ added in v0.1.5
type ArchiveSegmentInfo struct {
ID string `json:"id"`
Bytes int64 `json:"bytes"`
Lines int `json:"lines"`
FirstRecord int `json:"first_record"`
LastRecord int `json:"last_record"`
}
ArchiveSegmentInfo identifies text and its canonical record range. A record may span segments. Lines are wrapped at UTF-8 boundaries, at most 4096 bytes.
type ArchiveSource ¶ added in v0.1.5
ArchiveSource identifies the captured path. IDs are provenance, not graph edges to resolve, filesystem paths, or authority to access another session.
type ArchiveStore ¶ added in v0.1.5
type ArchiveStore struct {
// contains filtered or unexported fields
}
ArchiveStore is an application-owned storage boundary, not a model-facing service. Construct a separately allowlisted ArchiveReader using Bind. Its lifetime must remain within the owning repository/Handle lifetime.
func (*ArchiveStore) Bind ¶ added in v0.1.5
func (s *ArchiveStore) Bind(ids []string) (*ArchiveReader, error)
Bind copies an allowlist derived by the caller from its active checkpoint path. Empty references authorize nothing, including already published orphans. This is an application binding operation, not a model operation.
func (*ArchiveStore) Stage ¶ added in v0.1.5
func (s *ArchiveStore) Stage(ctx context.Context, source ArchiveSource, entries []harness.Entry) (*StagedArchive, error)
Stage captures canonical entries and searchable text without changing the Session. The caller supplies an immutable, raw selected path through TipID. External label/branch/checkpoint references remain inert provenance; no Harness graph reconstruction or transitive archive resolution is performed.
func (*ArchiveStore) Verify ¶ added in v0.1.5
func (s *ArchiveStore) Verify(ctx context.Context, id string) (ArchiveInfo, error)
Verify checks the entire object digest, manifest, canonical records and text segments. This privileged storage operation does not authorize model access.
type ChildIndexEntry ¶ added in v0.1.9
type ChildIndexEntry struct {
Schema string `json:"schema"`
Version int `json:"version"`
ChildSessionID string `json:"child_session_id"`
ParentSessionID string `json:"parent_session_id"`
ParentRunID string `json:"parent_run_id,omitempty"`
AgentID string `json:"agent_id"`
AgentKind string `json:"agent_kind,omitempty"`
CreatedAt time.Time `json:"created_at"`
// State is a cache of the child's lifecycle, filled only by the mirror that
// owns it. An entry published at creation or backfilled from a scan carries
// no state, because neither can know one.
State ChildIndexState `json:"state,omitempty"`
EndedAt time.Time `json:"ended_at,omitzero"`
}
ChildIndexEntry is the durable parent-side record of one child session. It records lineage and existence only: the child's own session.json and transcript stay the single home of its metadata, so an entry can always be repaired from the session it names instead of disagreeing with it.
func ReadChildIndexEntry ¶ added in v0.1.9
func ReadChildIndexEntry(path, parentID string) (ChildIndexEntry, error)
ReadChildIndexEntry reads and validates one parent-side child entry. parentID is the parent whose index directory holds the entry: an entry naming another parent does not describe a child of that index.
type ChildIndexState ¶ added in v0.1.9
type ChildIndexState string
ChildIndexState is the parent-side lifecycle state of one indexed child. It is a cache for a parent-side lookup: the child's own journal and session record stay authoritative for everything pips lists.
const ( // ChildIndexStateRunning covers a child that owns its session, whether its // run has started or not. ChildIndexStateRunning ChildIndexState = "running" // ChildIndexStateSucceeded means the child returned a validated result. ChildIndexStateSucceeded ChildIndexState = "succeeded" // ChildIndexStateFailed means the child ended without a usable result. ChildIndexStateFailed ChildIndexState = "failed" // ChildIndexStateCanceled means cancellation or a deadline stopped the child. ChildIndexStateCanceled ChildIndexState = "canceled" // ChildIndexStateInterrupted means reconciliation closed an orphan execution. ChildIndexStateInterrupted ChildIndexState = "interrupted" )
type Counts ¶ added in v0.1.9
type Counts struct {
Entries int `json:"entries"`
Messages int `json:"messages"`
Turns int `json:"turns"`
ToolCalls int `json:"tool_calls"`
}
Counts is the bounded projection of a session's size, maintained by writers so a listing never has to read the transcript.
type CreateOptions ¶
type CreateOptions struct {
WorkspaceID string
WorkspacePath string
RetainEmpty bool
Kind Kind
ParentSessionID string
ParentRunID string
Agent string
// SubagentIdentity is an optional versioned, non-secret identity snapshot
// for a child. Legacy callers may omit it; new child executions supply it.
SubagentIdentity *SubagentIdentity
TeamWorker *TeamWorkerLineage
}
CreateOptions are the non-secret attributes persisted in a session header.
type ForkOptions ¶
type ForkOptions struct {
AtEntryID string
}
ForkOptions select the source node copied into a new Session. An empty node selects the source's current leaf.
type ForkSubagentOptions ¶ added in v0.1.9
type ForkSubagentOptions struct {
// ParentSessionID is the session the new child belongs to. It is the new
// child's parent, which for a resume is the parent conversation rather than
// the source child.
ParentSessionID string
ParentRunID string
Agent string
// SubagentIdentity is the new child's frozen identity snapshot. It
// replaces any identity carried by the source header.
SubagentIdentity *SubagentIdentity
// AtEntryID selects the source node copied into the new child. An empty
// value selects the source's current leaf.
AtEntryID string
}
ForkSubagentOptions identify the source node copied into a new child Session and the lineage the copy belongs to.
type FormatInfo ¶ added in v0.1.9
type FormatInfo struct {
StoreVersion int `json:"store_version"`
ChatVersion int `json:"chat_version"`
JournalVersion int `json:"journal_version"`
}
FormatInfo pins the format versions a session was written with.
type GCReport ¶ added in v0.1.9
type GCReport struct {
// Deleted lists the session-relative paths that were removed.
Deleted []string
// Retained is the number of media files left in place.
Retained int
// Bytes is the total size of the deleted files.
Bytes int64
}
GCReport summarizes one media garbage-collection pass.
func PruneSessionMedia ¶ added in v0.1.9
func PruneSessionMedia( ctx context.Context, sessionDir string, age time.Duration, dryRun bool, ) (GCReport, error)
PruneSessionMedia removes the opened session's unreferenced media older than age. It returns the plan without deleting anything when dryRun is set. An unreadable reference aborts the prune before any deletion.
type GitRef ¶ added in v0.1.9
type GitRef struct {
Root string `json:"root,omitempty"`
Remotes []string `json:"remotes,omitempty"`
HeadCommit string `json:"head_commit,omitempty"`
HeadBranch string `json:"head_branch,omitempty"`
}
GitRef records the repository state observed when the session was written.
type Group ¶ added in v0.1.9
type Group struct {
// Key is the group directory name.
Key string
// Dir is the absolute group directory.
Dir string
// Path is the original workspace path, empty when the group has no readable
// workspace record.
Path string
}
Group is one resolved workspace group.
func (Group) SessionDirOf ¶ added in v0.1.9
SessionDirOf returns the absolute session directory inside one group.
type Handle ¶
type Handle struct {
// contains filtered or unexported fields
}
Handle owns a locked, writable Harness session.
func (*Handle) Close ¶
Close closes the writable store before releasing its writer lock. It is safe to call more than once and returns the first close result each time.
func (*Handle) Dir ¶ added in v0.1.9
Dir returns the absolute directory holding this session's durable files.
func (*Handle) ModelDir ¶ added in v0.1.9
ModelDir returns the model-input snapshot directory of this session.
func (*Handle) StateDir ¶ added in v0.1.9
StateDir returns the derived state sidecar directory of this session.
func (*Handle) UpdateIndex ¶ added in v0.1.9
func (h *Handle) UpdateIndex(mutate func(*MetadataRecord) error) error
UpdateIndex mutates and republishes the durable session index record. It is how higher layers record a title, summary, model, or git provenance without touching the transcript.
type Journal ¶ added in v0.1.9
type Journal struct {
// contains filtered or unexported fields
}
Journal is an append-only writer over one events.jsonl. It is safe for concurrent use and assigns a dense, monotonic sequence.
func OpenJournal ¶ added in v0.1.9
OpenJournal opens (creating when absent) the journal at path for appending. An existing journal is scanned once so the sequence continues rather than restarting, and a torn final line from an interrupted append is dropped so this writer never appends onto a partial record.
func (*Journal) Append ¶ added in v0.1.9
func (j *Journal) Append(records ...JournalRecord) error
Append writes records, filling in the schema, sequence, and time when unset. A record carrying another session's id is rejected.
type JournalRecord ¶ added in v0.1.9
type JournalRecord struct {
Schema string `json:"schema"`
Seq uint64 `json:"seq"`
Time time.Time `json:"time"`
SessionID string `json:"session_id"`
Type string `json:"type"`
Payload json.RawMessage `json:"payload"`
}
JournalRecord is one durable coding event. Payload holds the event body the owning package defines; this layer never interprets it.
func ReadJournal ¶ added in v0.1.9
func ReadJournal(path string, limit int) ([]JournalRecord, error)
ReadJournal returns up to limit records from oldest to newest. A zero limit reads every record. A trailing partial line is dropped; a malformed interior line is ErrJournalCorrupt. Durable records are written at their natural size, so there is no normal per-record byte budget here.
type Kind ¶
type Kind string
Kind identifies the product role of a durable Session.
const ( // KindConversation is a resumable user conversation. It is also the // interpretation of legacy headers that do not contain a kind. KindConversation Kind = "conversation" // KindSubagent is an internal child transcript owned by one conversation. KindSubagent Kind = "subagent" // KindTeamWorker is one attempt-scoped Team Worker transcript. It belongs to // its real Worktree Workspace and carries separate parent Team lineage. KindTeamWorker Kind = "team_worker" )
type LegacyWorkspaceRegistry ¶ added in v0.1.9
type LegacyWorkspaceRegistry struct {
// contains filtered or unexported fields
}
LegacyWorkspaceRegistry resolves a workspace identity to the path it was trusted at.
A pre-v2 session header recorded the workspace identity but not always the path, so the identity alone is not enough to place a session in its group. The workspace registry is what recovers the path, which is why a migration must consult it rather than grouping an identified session under "unknown".
func LoadLegacyWorkspaceRegistry ¶ added in v0.1.9
func LoadLegacyWorkspaceRegistry(path string) LegacyWorkspaceRegistry
LoadLegacyWorkspaceRegistry reads the registry at path. A missing, oversized, unreadable, or unknown-schema file yields an empty registry: the registry only improves attribution, so it never fails a migration.
func (LegacyWorkspaceRegistry) Len ¶ added in v0.1.9
func (r LegacyWorkspaceRegistry) Len() int
Len returns how many identities the registry resolved.
type LockedError ¶
LockedError reports the best-effort owner of a contended kernel lock. Owner metadata is diagnostic only; ErrLocked remains the authority.
func (*LockedError) Error ¶
func (e *LockedError) Error() string
func (*LockedError) Unwrap ¶
func (*LockedError) Unwrap() error
Unwrap preserves errors.Is compatibility with ErrLocked.
type MediaRef ¶ added in v0.1.9
MediaRef is one content-addressed media reference. Path is session-relative ("assets/image-<sha16>.jpg"); Digest is the lowercase hex SHA-256 of the referenced bytes.
func MediaRefFromSource ¶ added in v0.1.9
MediaRefFromSource validates a session-relative media path and digest.
type MediaStore ¶ added in v0.1.9
type MediaStore struct {
// contains filtered or unexported fields
}
MediaStore owns the media directories of exactly one session directory. It is a pure path scheme plus filesystem primitives; callers hold the session lock while they write or collect.
func NewMediaStore ¶ added in v0.1.9
func NewMediaStore(sessionDir string) (*MediaStore, error)
NewMediaStore returns a media store rooted at one absolute session directory.
func (*MediaStore) CopyTo ¶ added in v0.1.9
func (m *MediaStore) CopyTo( ctx context.Context, destination *MediaStore, refs map[string]struct{}, ) error
CopyTo copies every media file refs names, plus the images/ original sharing a referenced assets/ base name, into destination. A missing source file is an error, so a fork never publishes a transcript with a dangling reference.
func (*MediaStore) Dir ¶ added in v0.1.9
func (m *MediaStore) Dir() string
Dir returns the session directory the store writes into.
func (*MediaStore) Enumerate ¶ added in v0.1.9
func (m *MediaStore) Enumerate(ctx context.Context) ([]MediaRef, error)
Enumerate lists every media file in images/ and assets/ with its digest and stat metadata. Each returned reference is complete and passes MediaRef.Valid. A missing directory is empty, not an error.
func (*MediaStore) GC ¶ added in v0.1.9
func (m *MediaStore) GC( ctx context.Context, refs map[string]struct{}, grace time.Duration, dryRun bool, ) (GCReport, error)
GC removes media files that refs does not name and whose modification time is older than grace. A referenced assets/<base> keeps the matching images/<base> original. It returns what it removed and never deletes a file whose reference set membership or age is uncertain. A dry run reports the same plan without removing anything.
func (*MediaStore) Open ¶ added in v0.1.9
Open reads one referenced media file, verifies its SHA-256, and returns detached bytes. A missing file is ErrMediaMissing; a digest mismatch is ErrMediaCorrupt; an unsafe path or symlink is ErrMediaInvalid.
func (*MediaStore) PutModelCopy ¶ added in v0.1.9
func (m *MediaStore) PutModelCopy( ctx context.Context, original MediaRef, mimeType string, data []byte, ) (MediaRef, error)
PutModelCopy writes the bounded model-ready bytes under assets/ and returns its reference. When original names an existing original, the copy shares its base name so the original stays reachable from the copy's reference.
func (*MediaStore) PutOriginal ¶ added in v0.1.9
func (m *MediaStore) PutOriginal(ctx context.Context, mimeType string, data []byte) (MediaRef, error)
PutOriginal writes one original media file under images/ and returns its reference. The file name is derived from the bytes' SHA-256, so identical originals converge on one file.
type Metadata ¶
type Metadata struct {
ID string
CreatedAt time.Time
UpdatedAt time.Time
Path string
WorkspaceID string
WorkspacePath string
RetainEmpty bool
Kind Kind
ParentSessionID string
ParentEntryID string
ParentRunID string
Agent string
SubagentIdentity SubagentIdentity
TeamWorker TeamWorkerLineage
Name string
Preview string
CurrentLeafID string
NodeCount int
BranchCount int
Truncated bool
// Title is the session title and TitleManual reports that the user set it,
// so automatic titling must leave it alone.
Title string
TitleManual bool
// Summary, LastTurnSummary, and LastRecap are bounded model-written text kept
// in the index so listing surfaces never read the transcript.
Summary string
LastTurnSummary string
LastRecap string
// Model is the model in use when the index record was last written.
Model string
// Git records the repository state observed when the index record was written.
Git *GitRef
// Counts is the writer-maintained size projection.
Counts Counts
}
Metadata is the typed coding projection of Harness session metadata.
func (Metadata) BelongsToWorkspace ¶ added in v0.1.9
BelongsToWorkspace reports whether the session belongs to the workspace identified by workspacePath and workspaceID. Either match is enough.
The canonical workspace path is the ownership key. The workspace identity is provenance: it hashes the volume's device number and the directory's inode alongside the path, so a volume renumbering — which changes nothing the user did — would otherwise hide every session created before it. Identity matching stays so a session stored before a path was recorded still resolves.
type MetadataListing ¶ added in v0.1.7
type MetadataListing struct {
Sessions []Metadata
Unreadable int
// Truncated reports that the pass stopped early because its context was
// cancelled. The listing still carries every Session it read, so a cancelled
// read is partial data rather than a failure. Unreadable counts Sessions that
// could not be read at all and keeps that meaning separate.
Truncated bool
}
List returns typed session metadata in newest-first order without taking writer locks. MetadataListing is a header-level view of the store: every durable conversation with the metadata a statistics surface reads, plus how many Sessions could not be read at all and whether the pass stopped before reading the rest.
type MetadataRecord ¶ added in v0.1.9
type MetadataRecord struct {
Schema string `json:"schema"`
Version int `json:"version"`
ID string `json:"id"`
Workspace WorkspaceRef `json:"workspace"`
Kind Kind `json:"kind"`
Parent *ParentRef `json:"parent,omitempty"`
Agent string `json:"agent,omitempty"`
Subagent *SubagentRef `json:"subagent,omitempty"`
TeamWorker *TeamWorkerRef `json:"team_worker,omitempty"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
Title TitleRecord `json:"title"`
Summary string `json:"summary,omitempty"`
LastTurnSummary string `json:"last_turn_summary,omitempty"`
LastRecap string `json:"last_recap,omitempty"`
Model string `json:"model,omitempty"`
Git *GitRef `json:"git,omitempty"`
Counts Counts `json:"counts"`
RetainEmpty bool `json:"retain_empty,omitempty"`
Format FormatInfo `json:"format"`
}
MetadataRecord is one session's index entry, stored as session.json.
func NewMetadataRecord ¶ added in v0.1.9
func NewMetadataRecord(id string, workspace WorkspaceRef, kind Kind, createdAt time.Time) MetadataRecord
NewMetadataRecord returns a record initialized with the current schema.
func ReadMetadataRecord ¶ added in v0.1.9
func ReadMetadataRecord(path string) (MetadataRecord, error)
ReadMetadataRecord reads and validates one session.json.
type MigrateOptions ¶ added in v0.1.9
type MigrateOptions struct {
// Root is the legacy store root, the directory that holds the flat
// "<id>.jsonl" transcripts. It becomes the v2 store root.
Root string
// Apply performs the migration. When false the migrator reports what it
// would do and writes nothing.
Apply bool
// DeleteLegacy removes the migrated legacy files after a successful apply.
DeleteLegacy bool
// GoalsRoot is the optional legacy goals directory. Empty disables Goal
// migration.
GoalsRoot string
// WorkspacesFile is the pre-v2 workspace registry used to recover a session's
// workspace path when its header recorded only the identity. Empty selects
// the registry beside Root.
WorkspacesFile string
}
MigrateOptions configures one legacy store migration.
type MigrateReport ¶ added in v0.1.9
type MigrateReport struct {
Migrated []MigratedSession
Skipped []SkippedSession
Legacy []string
Unreadable []string
}
MigrateReport is what one migration did or would do.
func MigrateLegacyStore ¶ added in v0.1.9
func MigrateLegacyStore(ctx context.Context, options MigrateOptions) (MigrateReport, error)
MigrateLegacyStore moves every legacy flat transcript under options.Root into the layered store rooted at the same directory. It is idempotent: a session whose target already exists is skipped, and a v2 session is never overwritten. The caller owns progress reporting.
type MigratedSession ¶ added in v0.1.9
type MigratedSession struct {
ID string
WorkspacePath string
SessionDir string
Entries int
Prompts int
Archives int
HadState bool
HadGoals bool
}
MigratedSession is one legacy session moved into the layered store.
type ModelSnapshot ¶ added in v0.1.9
type ModelSnapshot struct {
// contains filtered or unexported fields
}
ModelSnapshot owns the model directory of one session. It records the system prompt, its render inputs, and the tool definitions sent on the latest call.
func OpenModelSnapshot ¶ added in v0.1.9
func OpenModelSnapshot(dir string) (*ModelSnapshot, error)
OpenModelSnapshot creates dir when needed and returns the snapshot layer for it. The stored path is cleaned and absolute, and dir must resolve to a real directory rather than a symlink.
func (*ModelSnapshot) Dir ¶ added in v0.1.9
func (s *ModelSnapshot) Dir() string
Dir returns the absolute model snapshot directory.
func (*ModelSnapshot) ReadJSON ¶ added in v0.1.9
func (s *ModelSnapshot) ReadJSON(name string, target any) (bool, error)
ReadJSON strictly decodes one JSON snapshot payload into target. It reports false without an error when name was never written. Unknown fields, invalid names, and payloads larger than 8 MiB are errors.
func (*ModelSnapshot) ReadSystemPrompt ¶ added in v0.1.9
func (s *ModelSnapshot) ReadSystemPrompt() (string, bool, error)
ReadSystemPrompt returns the stored system prompt. It reports false without an error when the prompt was never written, and false with an error when the file is unreadable, larger than 4 MiB, or not a regular file.
func (*ModelSnapshot) WriteJSON ¶ added in v0.1.9
func (s *ModelSnapshot) WriteJSON(name string, value any) error
WriteJSON atomically publishes one JSON snapshot payload under name. Name must be a single path component ending in ".json" and value must encode to at most 8 MiB.
func (*ModelSnapshot) WriteSystemPrompt ¶ added in v0.1.9
func (s *ModelSnapshot) WriteSystemPrompt(text string) error
WriteSystemPrompt atomically publishes the rendered system prompt. Text larger than 4 MiB is rejected.
type OpenOptions ¶
type OpenOptions struct {
ID string
WorkspaceID string
// WorkspacePath is the canonical path of the workspace claiming the session.
// It is the ownership key; see [Metadata.BelongsToWorkspace].
WorkspacePath string
}
OpenOptions identify a stored session and the workspace allowed to own it.
type OpenTeamWorkerOptions ¶
type OpenTeamWorkerOptions struct {
ID string
WorkspaceID string
Lineage TeamWorkerLineage
}
OpenTeamWorkerOptions identifies a Team Worker and the exact resource lineage allowed to own it.
type ParentRef ¶ added in v0.1.9
type ParentRef struct {
SessionID string `json:"session_id,omitempty"`
EntryID string `json:"entry_id,omitempty"`
RunID string `json:"run_id,omitempty"`
}
ParentRef records the session a fork or child was created from.
type Repository ¶
type Repository struct {
// contains filtered or unexported fields
}
Repository owns one layered session store: workspace groups of one directory per session, each holding its own index record, transcript, and sidecars.
func NewRepository ¶
func NewRepository(dir string) (*Repository, error)
NewRepository returns a session repository rooted at dir.
func (*Repository) Archives ¶ added in v0.1.5
func (r *Repository) Archives(handle *Handle) (*ArchiveStore, error)
Archives binds storage ownership without enumerating or creating any objects.
func (*Repository) CopyArchives ¶ added in v0.1.5
func (r *Repository) CopyArchives(ctx context.Context, source *Handle, destinationID string, ids []string) error
CopyArchives publishes independent, verified copies in a reserved destination session before its transcript is published. The caller must hold its writer lock and derive ids from the selected fork path. No destination Handle is required because the fork transcript does not exist yet. Provenance and IDs remain unchanged; neither source deletion nor old checkpoint references create transitive dependencies. Failure may leave inaccessible orphan objects.
func (*Repository) Create ¶
func (r *Repository) Create(ctx context.Context, options CreateOptions) (*Handle, error)
Create reserves and locks a new session. By default its JSONL file is created when the owning Harness Session persists its first entry. Callers that publish the ID before the first entry can retain an empty durable file.
func (*Repository) Delete ¶
func (r *Repository) Delete(ctx context.Context, id string) (resultErr error)
Delete permanently removes one durable conversation and its whole session directory, including archives and derived sidecars. Child and Team Worker transcripts are never deleted here.
func (*Repository) Dir ¶
func (r *Repository) Dir() string
Dir returns the absolute session repository directory.
func (*Repository) Fork ¶
func (r *Repository) Fork( ctx context.Context, source *Handle, options ForkOptions, ) (*Handle, error)
Fork creates and locks a failure-atomic copy of source's selected path. The source remains open and unchanged; callers own the returned Handle. Referenced archives are independently published for the destination before its transcript. Errors may leave unpublished-to-the-model archive objects; never remove them based only on a failed or durability-uncertain transcript publication.
func (*Repository) ForkSubagent ¶ added in v0.1.9
func (r *Repository) ForkSubagent( ctx context.Context, source *Handle, options ForkSubagentOptions, ) (*Handle, error)
ForkSubagent failure-atomically copies one completed source child Session into a new child Session owned by options.ParentSessionID. The source stays unchanged and readable, so the same source can be resumed more than once. The new child inherits the source transcript, its tool calls and results, and its checkpoint and archive references.
func (*Repository) Layout ¶ added in v0.1.9
func (r *Repository) Layout() StoreLayout
Layout returns the store layout this repository resolves session paths with.
func (*Repository) ListMetadata ¶ added in v0.1.7
func (r *Repository) ListMetadata(ctx context.Context) (MetadataListing, error)
ListMetadata returns header-level metadata for every durable conversation without reading session bodies. It reads one bounded entry per Session instead of the picker's full prefix, which is what makes a statistics surface cheap; the returned Sessions therefore carry header fields (id, kind, creation time) and no name, preview, or transcript counts.
A Session whose file fails the security check is skipped and counted rather than failing the whole listing, because one bad file must not blank a page that only reduces history. A cancelled context stops the pass and marks the listing truncated; the Sessions read so far are still returned and sorted.
func (*Repository) ListSubagents ¶
ListSubagents returns newest-first child metadata for exactly one parent conversation without taking writer locks. The parent's workspace is matched by path or identity, so a volume renumbering does not hide its children.
The parent's own index directory answers the read in O(children). An index that is absent, incomplete, or damaged falls back to the store-wide scan and is then rebuilt from what that scan found, so a store whose index cannot be written degrades to the scan — correct, and only slower — instead of failing a listing.
func (*Repository) ListTeamWorkers ¶
func (r *Repository) ListTeamWorkers( ctx context.Context, parentSessionID string, teamID team.ID, limit int, ) ([]Metadata, error)
ListTeamWorkers returns a bounded newest-first projection for exactly one Lead Session and Team. Worker Workspace identities remain their real values.
func (*Repository) Open ¶
func (r *Repository) Open(ctx context.Context, options OpenOptions) (*Handle, error)
Open locks and opens a stored session after verifying its workspace owner.
func (*Repository) OpenTeamWorker ¶
func (r *Repository) OpenTeamWorker( ctx context.Context, options OpenTeamWorkerOptions, ) (*Handle, error)
OpenTeamWorker locks and opens one Team Worker only after verifying its real Workspace and every durable lineage component.
func (*Repository) PruneMedia ¶ added in v0.1.9
func (r *Repository) PruneMedia( ctx context.Context, id string, age time.Duration, dryRun bool, ) (GCReport, error)
PruneMedia removes one stored session's unreferenced media older than age. It takes the session's writer lock, so a session another process holds is reported as locked instead of being pruned under a live writer.
func (*Repository) UpdateChildIndexState ¶ added in v0.1.9
func (r *Repository) UpdateChildIndexState( child Metadata, state ChildIndexState, at time.Time, ) error
UpdateChildIndexState refreshes the parent-side index entry of one child after a lifecycle transition. Like every index write it is best-effort: the child's journal is authoritative, so a missing entry or an unwritable index leaves the caller's lifecycle result unchanged.
It is the only writer of an entry's state. An entry published at creation or backfilled from a scan carries none, so a state this build can read always came from a lifecycle transition it observed.
type SearchDoc ¶ added in v0.1.9
type SearchDoc struct {
Schema string `json:"schema"`
ID string `json:"id"`
WorkspaceID string `json:"workspace_id"`
Title string `json:"title,omitempty"`
Summary string `json:"summary,omitempty"`
Prompts []string `json:"prompts,omitempty"`
UpdatedAt time.Time `json:"updated_at"`
Hash string `json:"hash"`
}
SearchDoc is one session's derived search document. It is never authoritative: it can always be rebuilt from the transcript and the session metadata record.
func BuildSearchDoc ¶ added in v0.1.9
func BuildSearchDoc(record MetadataRecord, prompts []string) SearchDoc
BuildSearchDoc projects a metadata record and its prompts into a search document with a normalized, bounded prompt list and a content hash.
func ReadSearchDoc ¶ added in v0.1.9
ReadSearchDoc reads and validates one search document. A missing file is reported as an os.ErrNotExist so the caller can rebuild the document.
type SkippedSession ¶ added in v0.1.9
type SkippedSession struct {
ID string
// Reason is "already migrated", "unreadable transcript", or
// "not a harness transcript".
Reason string
}
SkippedSession is one legacy transcript the migration left alone.
type StagedArchive ¶ added in v0.1.5
type StagedArchive struct {
// contains filtered or unexported fields
}
StagedArchive owns one unpublished private temporary file. Close always removes only that temporary name, never a published content-addressed object. Publish and Close are serialized; publish is idempotent until Close.
func (*StagedArchive) Close ¶ added in v0.1.5
func (s *StagedArchive) Close() error
Close releases staging resources. It is safe after failed/uncertain Publish.
func (*StagedArchive) ID ¶ added in v0.1.5
func (s *StagedArchive) ID() string
ID is known before publication so a candidate checkpoint can be validated.
func (*StagedArchive) Info ¶ added in v0.1.5
func (s *StagedArchive) Info() ArchiveInfo
Info returns detached archive metadata.
func (*StagedArchive) Publish ¶ added in v0.1.5
func (s *StagedArchive) Publish(ctx context.Context) error
Publish verifies the complete staged object, exclusively publishes its final name and syncs the owning directory. Existing identical objects are reused; different/corrupt objects are never overwritten. It does not commit a Session checkpoint and does not grant retrieval permission.
type StateStore ¶ added in v0.1.9
type StateStore struct {
// contains filtered or unexported fields
}
StateStore owns the derived, rebuildable state directory of one session. It reads and writes the small sidecars there (plan mode, usage, signals, rewind points) and is never authoritative for conversation content.
func OpenStateStore ¶ added in v0.1.9
func OpenStateStore(dir string) (*StateStore, error)
OpenStateStore opens the state directory of one session, creating it when absent. The directory is private and must be a real directory rather than a symlink.
func (*StateStore) AppendJSONL ¶ added in v0.1.9
func (s *StateStore) AppendJSONL(name string, values ...any) error
AppendJSONL appends one compact JSON value per line. An empty values slice writes nothing and creates no file.
func (*StateStore) Dir ¶ added in v0.1.9
func (s *StateStore) Dir() string
Dir returns the absolute state directory.
func (*StateStore) ReadJSON ¶ added in v0.1.9
func (s *StateStore) ReadJSON(name string, target any) (bool, error)
ReadJSON decodes one state sidecar into target. A missing file reports (false, nil); a present but unreadable or undecodable file reports an error wrapping ErrState.
func (*StateStore) ReadJSONL ¶ added in v0.1.9
func (s *StateStore) ReadJSONL(name string, limit int) ([][]byte, error)
ReadJSONL returns up to limit raw JSON lines oldest first. A limit <= 0 uses the default; a missing file reports (nil, nil). A trailing partial line is dropped, while a malformed interior line wraps ErrState.
func (*StateStore) Remove ¶ added in v0.1.9
func (s *StateStore) Remove(name string) error
Remove deletes one state sidecar. A missing file is not an error.
type StoreLayout ¶ added in v0.1.9
type StoreLayout struct {
// contains filtered or unexported fields
}
StoreLayout resolves every on-disk path of the layered session store rooted at one directory. It is a pure value: it holds the path scheme and never reads or creates anything. Use StoreRoot to find or create what the scheme describes.
func NewStoreLayout ¶ added in v0.1.9
func NewStoreLayout(root string) (StoreLayout, error)
NewStoreLayout returns a layout rooted exactly at root.
func (StoreLayout) ArchiveDir ¶ added in v0.1.9
func (l StoreLayout) ArchiveDir(workspacePath, id string) string
ArchiveDir returns the content-addressed archive directory.
func (StoreLayout) ArchiveRelDir ¶ added in v0.1.9
func (l StoreLayout) ArchiveRelDir(workspacePath, id string) []string
ArchiveRelDir returns the archive directory relative to the store root as single path components.
func (StoreLayout) AssetsDir ¶ added in v0.1.9
func (l StoreLayout) AssetsDir(workspacePath, id string) string
AssetsDir returns the bounded model-ready media copy directory.
func (StoreLayout) ChildIndexEntryDir ¶ added in v0.1.9
func (l StoreLayout) ChildIndexEntryDir(workspacePath, parentID, childID string) string
ChildIndexEntryDir returns the directory of one indexed child.
func (StoreLayout) ChildIndexEntryFile ¶ added in v0.1.9
func (l StoreLayout) ChildIndexEntryFile(workspacePath, parentID, childID string) string
ChildIndexEntryFile returns the index entry path of one indexed child.
func (StoreLayout) CompactionDir ¶ added in v0.1.9
func (l StoreLayout) CompactionDir(workspacePath, id string) string
CompactionDir returns the compaction checkpoint directory.
func (StoreLayout) GroupDir ¶ added in v0.1.9
func (l StoreLayout) GroupDir(workspacePath string) string
GroupDir returns the absolute group directory for a workspace path.
func (StoreLayout) GroupKey ¶ added in v0.1.9
func (l StoreLayout) GroupKey(workspacePath string) (key string, fallback bool, err error)
GroupKey returns the group directory name for a workspace path.
The key is the URL-escaped cleaned path when it fits in a single filesystem name; otherwise it is a bounded fallback derived from the path digest and the caller must persist the original path with StoreRoot.EnsureGroup.
func (StoreLayout) ImagesDir ¶ added in v0.1.9
func (l StoreLayout) ImagesDir(workspacePath, id string) string
ImagesDir returns the session media originals directory.
func (StoreLayout) JournalFile ¶ added in v0.1.9
func (l StoreLayout) JournalFile(workspacePath, id string) string
JournalFile returns the coding event journal path.
func (StoreLayout) LockFile ¶ added in v0.1.9
func (l StoreLayout) LockFile(workspacePath, id string) string
LockFile returns the single-writer lock path.
func (StoreLayout) MetadataFile ¶ added in v0.1.9
func (l StoreLayout) MetadataFile(workspacePath, id string) string
MetadataFile returns the session index record path.
func (StoreLayout) ModelDir ¶ added in v0.1.9
func (l StoreLayout) ModelDir(workspacePath, id string) string
ModelDir returns the model-input snapshot directory.
func (StoreLayout) Root ¶ added in v0.1.9
func (l StoreLayout) Root() string
Root returns the absolute store root.
func (StoreLayout) SearchFile ¶ added in v0.1.9
func (l StoreLayout) SearchFile(workspacePath, id string) string
SearchFile returns the derived search document path.
func (StoreLayout) SessionDir ¶ added in v0.1.9
func (l StoreLayout) SessionDir(workspacePath, id string) string
SessionDir returns the absolute directory of one session.
func (StoreLayout) SessionRelDir ¶ added in v0.1.9
func (l StoreLayout) SessionRelDir(workspacePath, id string) []string
SessionRelDir returns the session directory relative to the store root, split into single path components. Callers that must stay descriptor-relative walk these components one at a time.
func (StoreLayout) StateDir ¶ added in v0.1.9
func (l StoreLayout) StateDir(workspacePath, id string) string
StateDir returns the derived state directory.
func (StoreLayout) SubagentIndexFile ¶ added in v0.1.9
func (l StoreLayout) SubagentIndexFile(workspacePath, id string) string
SubagentIndexFile returns the child index's completeness marker path.
func (StoreLayout) SubagentsDir ¶ added in v0.1.9
func (l StoreLayout) SubagentsDir(workspacePath, id string) string
SubagentsDir returns the parent-side child index directory.
func (StoreLayout) TerminalDir ¶ added in v0.1.9
func (l StoreLayout) TerminalDir(workspacePath, id string) string
TerminalDir returns the tool output log directory.
func (StoreLayout) TranscriptFile ¶ added in v0.1.9
func (l StoreLayout) TranscriptFile(workspacePath, id string) string
TranscriptFile returns the authoritative transcript path.
type StoreRoot ¶ added in v0.1.9
type StoreRoot struct {
// contains filtered or unexported fields
}
StoreRoot is the session store on disk: the root directory plus the operations that read or create the tree beneath it. StoreLayout says where everything goes; this is the type that touches the filesystem to find it.
func NewStoreRoot ¶ added in v0.1.9
NewStoreRoot returns the store rooted exactly at root. It reads and creates nothing.
func (StoreRoot) EnsureGroup ¶ added in v0.1.9
EnsureGroup creates the group directory and its workspace record.
func (StoreRoot) FindSession ¶ added in v0.1.9
FindSession locates one session directory by id across every group. It validates the id and reports false when no group holds it.
func (StoreRoot) Groups ¶ added in v0.1.9
Groups returns every workspace group in the store, sorted by key.
func (StoreRoot) Layout ¶ added in v0.1.9
func (s StoreRoot) Layout() StoreLayout
Layout returns the pure path scheme of this store.
type SubagentIdentity ¶
type SubagentIdentity struct {
Schema string
AgentID string
Kind string
Name string
DefinitionSchema string
DefinitionDigest string
DefinitionSource string
GenerationID uint64
PlanDigest string
}
SubagentIdentity is the non-secret session-header subset of a compiled child execution plan. The full plan remains in the child journal; this header lets session listing and lineage validation retain stable identity even after the definition file changes or disappears.
func (SubagentIdentity) IsZero ¶
func (i SubagentIdentity) IsZero() bool
IsZero reports whether the legacy session header carries no identity snapshot. It is valid only for historical child sessions.
type SubagentRef ¶ added in v0.1.9
type SubagentRef struct {
Schema string `json:"schema,omitempty"`
AgentID string `json:"agent_id,omitempty"`
Kind string `json:"kind,omitempty"`
Name string `json:"name,omitempty"`
DefinitionSchema string `json:"definition_schema,omitempty"`
DefinitionDigest string `json:"definition_digest,omitempty"`
DefinitionSource string `json:"definition_source,omitempty"`
GenerationID uint64 `json:"generation_id,omitempty"`
PlanDigest string `json:"plan_digest,omitempty"`
}
SubagentRef is the JSON projection of one subagent identity.
type TeamWorkerLineage ¶
type TeamWorkerLineage struct {
ParentSessionID string
TeamID team.ID
MemberID team.MemberID
TaskID team.TaskID
AttemptID team.AttemptID
ContinuationID continuation.ID
}
TeamWorkerLineage binds an attempt-scoped Worker Session to its Lead and exact durable Team resources.
type TeamWorkerRef ¶ added in v0.1.9
type TeamWorkerRef struct {
ParentSessionID string `json:"parent_session_id,omitempty"`
TeamID string `json:"team_id,omitempty"`
MemberID string `json:"team_member_id,omitempty"`
TaskID string `json:"team_task_id,omitempty"`
AttemptID string `json:"team_attempt_id,omitempty"`
ContinuationID string `json:"continuation_id,omitempty"`
}
TeamWorkerRef is the JSON projection of one Team Worker lineage.
type TitleRecord ¶ added in v0.1.9
type TitleRecord struct {
Text string `json:"text,omitempty"`
// Manual is true when the user set the title, so automatic titling must not
// overwrite it.
Manual bool `json:"manual,omitempty"`
}
TitleRecord is the session title and how it was set.
type WorkspaceRecord ¶ added in v0.1.9
type WorkspaceRecord struct {
Schema string `json:"schema"`
Key string `json:"key"`
Path string `json:"path,omitempty"`
CreatedAt time.Time `json:"created_at"`
}
WorkspaceRecord identifies one workspace group directory.
type WorkspaceRef ¶ added in v0.1.9
WorkspaceRef records the owning workspace identity and its path.
Source Files
¶
- archive.go
- archive_format.go
- archive_io_unix.go
- archive_read.go
- archive_render.go
- child_index.go
- deferred_store.go
- doc.go
- file_security_unix.go
- fileio.go
- journal.go
- layout.go
- lock.go
- lock_unix.go
- media.go
- media_gc.go
- metadata.go
- migrate.go
- repository.go
- repository_archive.go
- search.go
- snapshot.go
- state.go
- store.go
- workspaceregistry.go