session

package
v0.1.3 Latest Latest
Warning

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

 Go to latest Published: Sep 18, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Overview

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

Index

Constants

This section is empty.

Variables

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

Functions

func ValidateID 

func ValidateID(id string) error

ValidateID verifies that id is safe to use as a durable session name.

Types

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

func (h *Handle) Metadata() Metadata

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

func (*Handle) Session 

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

Session returns the durable conversation tree owned by the handle.

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 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 Metadata 

type Metadata struct {
	ID               string
	CreatedAt        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
}

Metadata is the typed coding projection of Harness session metadata.

type OpenOptions 

type OpenOptions struct {
	ID          string
	WorkspaceID 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 Repository 

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

Repository owns one directory of coding session files and their lock files.

func NewRepository 

func NewRepository(dir string) (*Repository, error)

NewRepository returns a session repository rooted at dir.

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. Missing conversations are already in the desired state and therefore succeed. Child and Team Worker transcripts are never deleted through this user-facing boundary.

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.

func (*Repository) List 

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

List returns typed session metadata in newest-first order without taking writer locks.

func (*Repository) ListSubagents 

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

ListSubagents returns newest-first child metadata for exactly one Workspace and parent conversation without taking writer locks.

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.

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.