session

package
v0.1.9 Latest Latest
Warning

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

Go to latest
Published: Oct 19, 2026 License: Apache-2.0 Imports: 29 Imported by: 0

Documentation

Overview

Package session adds coding-application identity and single-writer ownership to the durable Harness session repository.

Index

Constants

View Source
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.

View Source
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.

View Source
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.

View Source
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.

View Source
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.

View Source
const LegacyWorkspaceFile = "workspaces.json"

LegacyWorkspaceFile is the pre-v2 workspace registry that sits beside the session store root.

View Source
const SearchSchema = "pips.coding.session.search/v1"

SearchSchema names the derived search document format.

Variables

View Source
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")
)
View Source
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.

View Source
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")
)
View Source
var ErrChildIndex = errors.New("coding session: invalid child index")

ErrChildIndex identifies an unreadable or unsupported parent-side child index record.

View Source
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.

View Source
var ErrLayout = errors.New("coding session: invalid store layout")

ErrLayout identifies an unusable session store layout input.

View Source
var ErrMetadata = errors.New("coding session: invalid metadata")

ErrMetadata identifies an unreadable or unsupported session metadata record.

View Source
var ErrSearch = errors.New("coding session: invalid search document")

ErrSearch identifies an invalid or unreadable search document.

View Source
var ErrSnapshot = errors.New("coding session: invalid model snapshot")

ErrSnapshot identifies an invalid model snapshot request or payload.

View Source
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

func CollectMediaReferences(ctx context.Context, sessionDir string) (map[string]struct{}, error)

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

func DefaultLegacyWorkspaceRegistryPath(storeRoot string) string

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

func IdleSince(sessionDir string) (time.Time, bool)

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

func LegacyStoreDetected(root string) bool

LegacyStoreDetected reports whether root still holds pre-v2 session files.

func MediaReferencesFromEntries added in v0.1.9

func MediaReferencesFromEntries(entries []harness.Entry) map[string]struct{}

MediaReferencesFromEntries collects the session-relative media paths every message in entries references, including nested tool-result content.

func MediaRelativePath added in v0.1.9

func MediaRelativePath(dir, name string) (string, error)

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

func ValidMediaReference(path, digest string) bool

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

func ValidateArchiveID(id string) error

ValidateArchiveID accepts only a lowercase SHA-256 content identity.

func ValidateID

func ValidateID(id string) error

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

func WriteSearchDoc(path string, doc SearchDoc) error

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

type ArchiveLine struct {
	Number int    `json:"number"`
	Text   string `json:"text"`
}

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

type ArchiveListRequest struct {
	ArchiveID string
	Offset    int
	Limit     int
}

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

type ArchiveReadRequest struct {
	ArchiveID string
	SegmentID string
	Offset    int
	Limit     int
}

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

List exposes only the supplied references; there is no caller-supplied session.

func (*ArchiveReader) Read added in v0.1.5

Read returns checked text, never an arbitrary file or raw path.

func (*ArchiveReader) Search added in v0.1.5

Search supports bounded literal/RE2 retrieval without filesystem globs.

type ArchiveSearchCursor added in v0.1.5

type ArchiveSearchCursor struct {
	SegmentID string `json:"segment_id"`
	Line      int    `json:"line"`
}

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

type ArchiveSource struct {
	SessionID string `json:"session_id"`
	TipID     string `json:"tip_id"`
}

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

func (g Group) SessionDirOf(id string) string

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

func (h *Handle) Close() error

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

func (h *Handle) Dir() string

Dir returns the absolute directory holding this session's durable files.

func (*Handle) Metadata

func (h *Handle) Metadata() Metadata

Metadata returns the session's typed, non-secret metadata.

func (*Handle) ModelDir added in v0.1.9

func (h *Handle) ModelDir() string

ModelDir returns the model-input snapshot directory of this session.

func (*Handle) Session

func (h *Handle) Session() *harness.Session

Session returns the durable conversation tree owned by the handle.

func (*Handle) StateDir added in v0.1.9

func (h *Handle) StateDir() string

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

func OpenJournal(path, sessionID string) (*Journal, error)

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.

func (*Journal) Close added in v0.1.9

func (j *Journal) Close() error

Close flushes and closes the journal. It is idempotent.

func (*Journal) Sequence added in v0.1.9

func (j *Journal) Sequence() uint64

Sequence returns the last assigned sequence.

func (*Journal) Sync added in v0.1.9

func (j *Journal) Sync() error

Sync flushes appended records to stable storage.

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.

func (LegacyWorkspaceRegistry) Path added in v0.1.9

func (r LegacyWorkspaceRegistry) Path(workspaceID string) (string, bool)

Path returns the recorded path for one workspace identity.

type LockedError

type LockedError struct {
	Path       string
	OwnerPID   int
	AcquiredAt time.Time
}

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

type MediaRef struct {
	Path     string
	Digest   string
	MIMEType string
	Width    int
	Height   int
	Bytes    int64
}

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

func MediaRefFromSource(path, digest, mimeType string, width, height int) (MediaRef, error)

MediaRefFromSource validates a session-relative media path and digest.

func (MediaRef) Base added in v0.1.9

func (r MediaRef) Base() string

Base returns the file name without its directory or extension.

func (MediaRef) Valid added in v0.1.9

func (r MediaRef) Valid() bool

Valid reports whether the reference is internally consistent.

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

func (m *MediaStore) Open(ctx context.Context, ref MediaRef) ([]byte, error)

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.

func (*MediaStore) WriteRef added in v0.1.9

func (m *MediaStore) WriteRef(ctx context.Context, ref MediaRef, data []byte) error

WriteRef publishes data at ref's session-relative path after verifying that the bytes match ref.Digest. It is the copy path used by fork.

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

func (m Metadata) BelongsToWorkspace(workspacePath, workspaceID string) bool

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) List

func (r *Repository) List(ctx context.Context) ([]Metadata, error)

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

func (r *Repository) ListSubagents(ctx context.Context, parent Metadata) ([]Metadata, error)

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

func ReadSearchDoc(path string) (SearchDoc, error)

ReadSearchDoc reads and validates one search document. A missing file is reported as an os.ErrNotExist so the caller can rebuild the document.

func (SearchDoc) Content added in v0.1.9

func (d SearchDoc) Content() string

Content returns the searchable text of the document: title, summary, and prompts joined by newlines with empty parts skipped.

func (SearchDoc) Match added in v0.1.9

func (d SearchDoc) Match(query string) bool

Match reports whether every whitespace-separated token of query occurs in the document content, case-insensitively. An empty query never matches.

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.

func (*StateStore) WriteJSON added in v0.1.9

func (s *StateStore) WriteJSON(name string, value any) error

WriteJSON atomically publishes value as one state sidecar.

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

func NewStoreRoot(root string) (StoreRoot, error)

NewStoreRoot returns the store rooted exactly at root. It reads and creates nothing.

func (StoreRoot) EnsureGroup added in v0.1.9

func (s StoreRoot) EnsureGroup(workspacePath string) (Group, error)

EnsureGroup creates the group directory and its workspace record.

func (StoreRoot) FindSession added in v0.1.9

func (s StoreRoot) FindSession(id string) (Group, bool, error)

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

func (s StoreRoot) Groups() ([]Group, error)

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.

func (StoreRoot) Root added in v0.1.9

func (s StoreRoot) Root() string

Root returns the absolute store root.

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

type WorkspaceRef struct {
	ID   string `json:"id"`
	Path string `json:"path,omitempty"`
}

WorkspaceRef records the owning workspace identity and its path.

Jump to

Keyboard shortcuts

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