bgreg

package

v0.1.1 Latest Latest Go to latest Published: Jun 7, 2026 License: MIT Imports: 11 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/elhenro/bee

Links

Open Source Insights

Documentation ¶

Rendered for

Overview ¶

Package bgreg is the per-session status sidecar registry for background bees. The bg engine writes; the agent-view TUI reads. One JSON file per session at <beeHome>/sessions/bg/<id>.status.json, written via temp+rename for atomic replacement.

Inbox IPC. Agent-view TUI appends user follow-up messages to a per-session JSONL file; bg loop tails it from a byte cursor at every turn boundary.

Index ¶

Variables
func InboxAppend(sessionID, text string) error
func InboxRemove(sessionID string) error
func Remove(sessionID string) error
func Truncate(s string) string
func Update(sessionID string, fn func(*Status) error) error
func Write(s Status) error
type Inbox
- func InboxDrain(sessionID string, cursor int64) ([]Inbox, int64, error)
type MergeState
type PruneOpts
type PruneResult
- func Prune(opts PruneOpts) PruneResult
type State
type Status
- func List() ([]Status, error)
- func Read(sessionID string) (Status, error)

Constants ¶

This section is empty.

Variables ¶

View Source

var ErrStaleUpdate = errors.New("bgreg: stale update (version moved during fn)")

ErrStaleUpdate signals that the status changed during an Update callback — indicates a writer bypassed the lock (used Write directly). Callers can retry Update.

Functions ¶

func InboxAppend ¶

func InboxAppend(sessionID, text string) error

func InboxRemove ¶

func InboxRemove(sessionID string) error

func Remove ¶

func Remove(sessionID string) error

func Truncate ¶

func Truncate(s string) string

func Update ¶

func Update(sessionID string, fn func(*Status) error) error

Update performs an atomic read-modify-write on the status for sessionID. fn receives a copy of the current Status; mutating fields and returning nil commits the change with a bumped Version. The status file is locked via a per-session sidecar (.lock) so concurrent Update calls — even across processes — serialize. fn returning a non-nil error aborts the write.

ErrStaleUpdate is returned if the on-disk Version advanced while fn ran (only possible if fn took longer than the lock acquisition retry window or if a writer bypassed Update — Write keeps last-writer-wins semantics).

func Write ¶

func Write(s Status) error

Write replaces the on-disk status atomically. Version is auto-incremented from the on-disk value (last-writer-wins). For race-free read-modify-write use Update instead — it serializes via a per-session lock and rejects stale updates.

Types ¶

type Inbox ¶

type Inbox struct {
	Text      string    `json:"text"`
	CreatedAt time.Time `json:"created_at"`
}

func InboxDrain ¶

func InboxDrain(sessionID string, cursor int64) ([]Inbox, int64, error)

InboxDrain returns every line written after cursor and the new cursor. Pass 0 on first call. Cursor lives in caller memory only.

type MergeState ¶

type MergeState string

MergeState tracks agent-mode branch lifecycle. Empty string for legacy bg sessions that don't run on a worktree.

const (
	MergeStateNone     MergeState = ""
	MergeStateUnmerged MergeState = "unmerged"
	MergeStateMerging  MergeState = "merging"
	MergeStateMerged   MergeState = "merged"
	MergeStateConflict MergeState = "conflict"
)

type PruneOpts ¶

type PruneOpts struct {
	MaxAge     time.Duration
	KeepNewest int
}

PruneOpts mirrors zzz.PruneOpts: thresholds are AND-ed. Zero disables the matching threshold. Active/awaiting sessions are always preserved — only terminal (done, failed) sidecars are candidates.

type PruneResult ¶

type PruneResult struct {
	RemovedIDs []string
	Errors     []error
}

PruneResult lists removed session IDs.

func Prune ¶

func Prune(opts PruneOpts) PruneResult

Prune sweeps ~/.bee/sessions/bg/ removing terminal Status sidecars per opts.

type State ¶

type State string

const (
	StateActive   State = "active"
	StateAwaiting State = "awaiting"
	StateIdle     State = "idle"
	StateDone     State = "done"
	StateFailed   State = "failed"
)

type Status ¶

type Status struct {
	SchemaV      int       `json:"schema_v"`
	Version      int       `json:"version"` // monotonic write-generation, used by Update CAS
	SessionID    string    `json:"session_id"`
	PID          int       `json:"pid"`
	State        State     `json:"state"`
	Task         string    `json:"task"`
	LastResponse string    `json:"last_response"`
	Model        string    `json:"model"`
	Provider     string    `json:"provider,omitempty"`
	Cwd          string    `json:"cwd"`
	StartedAt    time.Time `json:"started_at"`
	UpdatedAt    time.Time `json:"updated_at"`
	FinishedAt   time.Time `json:"finished_at,omitempty"`

	// agent-mode fields. Empty / zero on legacy bg sessions.
	WorktreePath string     `json:"worktree_path,omitempty"`
	Branch       string     `json:"branch,omitempty"`
	MergeState   MergeState `json:"merge_state,omitempty"`
	ConflictMsg  string     `json:"conflict_msg,omitempty"`
	InputTokens  int        `json:"input_tokens,omitempty"`
	OutputTokens int        `json:"output_tokens,omitempty"`
}

func List ¶

func List() ([]Status, error)

func Read ¶

func Read(sessionID string) (Status, error)

Source Files ¶

View all Source files

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