thread

package
v0.1.0-p8a.1 Latest Latest
Warning

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

 Go to latest Published: Aug 10, 2026 License: MIT Imports: 27 Imported by: 0

Documentation

Overview

Package thread defines durable local-coding thread identity and metadata.

Index

Constants

View Source 
const (
	DefaultCatalogScanLimit       = 10_000
	DefaultCatalogPageSize        = 100
	DefaultCatalogMaxPageSize     = 500
	DefaultCatalogSkipReportLimit = 50
)
View Source 
const (
	// LeaseSchemaVersion is the current diagnostic owner-record schema.
	LeaseSchemaVersion = 1
	// MaxLeaseOwnerBytes bounds untrusted diagnostic data in thread.lock.
	MaxLeaseOwnerBytes = 4 * 1024
)
View Source 
const (
	// SchemaVersion is the current on-disk CodingThread metadata schema.
	SchemaVersion = 1
	// MaxMetadataBytes bounds one descriptor independently of transcript size.
	MaxMetadataBytes = 32 * 1024
)
View Source 
const MaxPromptBytes = 1 << 20

Variables

View Source 
var ErrLeaseBusy = errors.New("coding thread lease busy")

ErrLeaseBusy classifies a coding thread already owned by another process.

Functions

func DisplayFromRequest 

func DisplayFromRequest(request string) (string, string, error)

DisplayFromRequest derives bounded picker text from an accepted request.

func IsCommittedPromptError 

func IsCommittedPromptError(err error) bool

IsCommittedPromptError reports whether err preserves a committed prompt.

func IsIndeterminatePromptError 

func IsIndeterminatePromptError(err error) bool

IsIndeterminatePromptError reports whether a prompt may have been written but was not confirmed durable.

func NewThreadID 

func NewThreadID() string

NewThreadID returns a new opaque coding-thread UUID.

func SessionKey 

func SessionKey(threadID string) string

SessionKey returns the canonical transcript session key for a thread.

func ValidatePrompt 

func ValidatePrompt(content string) error

ValidatePrompt checks the canonical coding prompt bound before any thread metadata or transcript state is created.

Types

type Catalog 

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

Catalog discovers bounded thread metadata without opening transcripts.

func NewCatalog 

func NewCatalog(store *Store, options CatalogOptions) (*Catalog, error)

NewCatalog creates a read-only catalog view over a metadata store.

func (*Catalog) Query 

func (c *Catalog) Query(ctx context.Context, query CatalogQuery) (CatalogPage, error)

Query returns one exact thread or a deterministically sorted page. Exact ID lookup bypasses scanning and project filtering so callers can report an explicit project mismatch rather than hiding the thread.

type CatalogOptions 

type CatalogOptions struct {
	ScanLimit       int
	PageSize        int
	MaxPageSize     int
	SkipReportLimit int
}

CatalogOptions bounds catalog work and result memory.

type CatalogPage 

type CatalogPage struct {
	Threads       []Metadata
	Skipped       []SkippedEntry
	SkippedTotal  int
	Scanned       int
	Matched       int
	ScanTruncated bool
	HasMore       bool
	NextOffset    int
}

CatalogPage is a bounded catalog response suitable for a TUI picker.

type CatalogQuery 

type CatalogQuery struct {
	ThreadID   string
	ProjectKey string
	All        bool
	Last       bool
	Offset     int
	Limit      int
}

CatalogQuery selects an exact thread or a bounded sorted page. ProjectKey is required by default; All deliberately widens the scope.

type CommittedPromptError 

type CommittedPromptError struct {
	ThreadID string
	Err      error
}

CommittedPromptError reports that a prompt reached canonical history even though a later finalization step failed. Retrying may duplicate the prompt.

func (*CommittedPromptError) Error 

func (e *CommittedPromptError) Error() string

func (*CommittedPromptError) Unwrap 

func (e *CommittedPromptError) Unwrap() error

type Compaction 

type Compaction struct {
	At       time.Time `json:"at"`
	Revision uint64    `json:"revision"`
}

Compaction records the latest durable compaction checkpoint, when present.

type IndeterminatePromptError 

type IndeterminatePromptError struct {
	ThreadID string
	Err      error
}

IndeterminatePromptError reports that a prompt write began, but its durable outcome could not be confirmed. Retrying may duplicate the prompt.

func (*IndeterminatePromptError) Error 

func (e *IndeterminatePromptError) Error() string

func (*IndeterminatePromptError) Unwrap 

func (e *IndeterminatePromptError) Unwrap() error

type Lease 

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

Lease is an exclusive, process-scoped writer claim on one coding thread.

func (*Lease) Owner 

func (l *Lease) Owner() LeaseOwner

Owner returns the diagnostic record written by this process.

func (*Lease) Release 

func (l *Lease) Release() error

Release unlocks and closes the lease. It is safe to call more than once.

func (*Lease) ThreadID 

func (l *Lease) ThreadID() string

ThreadID returns the leased coding thread ID.

type LeaseBusyError 

type LeaseBusyError struct {
	ThreadID string
	Owner    *LeaseOwner
}

LeaseBusyError reports a live owner when its bounded record was readable.

func (*LeaseBusyError) Error 

func (e *LeaseBusyError) Error() string

func (*LeaseBusyError) Unwrap 

func (e *LeaseBusyError) Unwrap() error

type LeaseOwner 

type LeaseOwner struct {
	SchemaVersion int       `json:"schema_version"`
	PID           int       `json:"pid"`
	Hostname      string    `json:"hostname,omitempty"`
	AcquiredAt    time.Time `json:"acquired_at"`
}

LeaseOwner is best-effort diagnostic information stored in thread.lock. The OS file lock, rather than this record, is the source of exclusivity.

type LocationInspection 

type LocationInspection struct {
	State     LocationState
	Persisted ProjectIdentity
	Current   *ProjectIdentity
}

LocationInspection never rebinds persisted metadata. candidateCWD is optional; when supplied after the stored root disappeared it is reported as a proposed move requiring explicit caller action.

func InspectLocation 

func InspectLocation(
	ctx context.Context,
	persisted ProjectIdentity,
	candidateCWD string,
) (LocationInspection, error)

InspectLocation returns an explicit availability/move/mismatch state for a persisted thread. It does not mutate or silently rebind project identity.

type LocationState 

type LocationState string

LocationState is the explicit resume-time relationship between persisted metadata and current disk state. 

const (
	LocationAvailable LocationState = "available"
	LocationMissing   LocationState = "missing"
	LocationMoved     LocationState = "moved"
	LocationMismatch  LocationState = "mismatch"
)

type Metadata 

type Metadata struct {
	SchemaVersion int             `json:"schema_version"`
	ThreadID      string          `json:"thread_id"`
	SessionKey    string          `json:"session_key"`
	CreatedAt     time.Time       `json:"created_at"`
	UpdatedAt     time.Time       `json:"updated_at"`
	Title         string          `json:"title"`
	Preview       string          `json:"preview"`
	Status        Status          `json:"status"`
	Project       ProjectIdentity `json:"project"`
	Model         string          `json:"model,omitempty"`
	Provider      string          `json:"provider,omitempty"`
	ParentThread  string          `json:"parent_thread_id,omitempty"`
	Compaction    *Compaction     `json:"last_compaction,omitempty"`
}

Metadata is the versioned, transcript-independent coding-thread descriptor. It is intentionally small enough to support catalog reads without loading canonical JSONL history.

func NewMetadata 

func NewMetadata(
	threadID string,
	project ProjectIdentity,
	firstRequest string,
	now time.Time,
) (Metadata, error)

NewMetadata creates a validated descriptor from the first accepted user request. Display text is derived locally without an additional model call.

func (Metadata) Validate 

func (m Metadata) Validate() error

Validate checks the complete persisted metadata contract.

type ProjectIdentity 

type ProjectIdentity struct {
	Kind            ProjectKind `json:"kind"`
	ProjectKey      string      `json:"project_key"`
	ProjectRoot     string      `json:"project_root"`
	InvocationCWD   string      `json:"invocation_cwd"`
	GitWorktreeRoot string      `json:"git_worktree_root,omitempty"`
	GitCommonDir    string      `json:"git_common_dir,omitempty"`
	GitOrigin       string      `json:"git_origin,omitempty"`
	GitBranch       string      `json:"git_branch,omitempty"`
	GitHead         string      `json:"git_head,omitempty"`
}

ProjectIdentity is a restart-stable snapshot of the invocation project. ProjectKey intentionally keys Git projects by worktree root, so separate worktrees remain separate projects even when they share GitCommonDir.

func ResolveProject 

func ResolveProject(ctx context.Context, cwd string) (ProjectIdentity, error)

ResolveProject resolves cwd and Git observations without writing to either the project or MintClaw state.

func (ProjectIdentity) Validate 

func (p ProjectIdentity) Validate() error

Validate checks persisted project identity without consulting current disk state. Availability and movement are inspected separately on resume.

type ProjectKind 

type ProjectKind string

ProjectKind identifies the root used to match coding threads. 

const (
	ProjectKindDirectory   ProjectKind = "directory"
	ProjectKindGitWorktree ProjectKind = "git_worktree"
)

type SkippedEntry 

type SkippedEntry struct {
	Entry  string
	Reason string
}

SkippedEntry is one bounded diagnostic for an unreadable catalog entry.

type Status 

type Status string

Status is the durable lifecycle state of a coding thread. 

const (
	StatusActive   Status = "active"
	StatusArchived Status = "archived"
)

type Store 

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

Store atomically persists direct-addressable thread metadata below one external coding state root.

func NewStore 

func NewStore(root string) (*Store, error)

NewStore creates a side-effect-free metadata store descriptor.

func (*Store) AcquireLease 

func (s *Store) AcquireLease(threadID string) (*Lease, error)

AcquireLease takes a non-blocking writer lease on an existing coding thread.

func (*Store) AppendUserMessage 

func (s *Store) AppendUserMessage(
	ctx context.Context,
	lease *Lease,
	metadata Metadata,
	content string,
) error

AppendUserMessage durably appends one accepted prompt to a thread's canonical JSONL transcript while holding its process lease.

func (*Store) Load 

func (s *Store) Load(threadID string) (Metadata, error)

Load reads and validates one descriptor without opening its transcript.

func (*Store) ProvisionThread 

func (s *Store) ProvisionThread(threadID string) error

ProvisionThread durably creates a private thread directory without publishing catalog-visible metadata.

func (*Store) Root 

func (s *Store) Root() string

Root returns the external coding state root.

func (*Store) Save 

func (s *Store) Save(metadata Metadata) error

Save atomically replaces one descriptor. A post-rename durability error is returned as fileutil.CommittedWriteError and must not be blindly retried.

func (*Store) ThreadRoot 

func (s *Store) ThreadRoot(threadID string) (string, error)

ThreadRoot returns the owner-scoped state root consumed by RuntimeLayout.

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.