sessionstate

package
v0.14.0 Latest Latest
Warning

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

Go to latest
Published: Nov 8, 2026 License: MIT Imports: 2 Imported by: 0

Documentation

Overview

Package sessionstate answers one question for every surface: what is this session doing right now. The phone (remote API `activity`), the TUI and the web dashboard all show its answer.

The answer combines facts other packages own; each comes in as a small input so its source stays where it is (Service):

  • Held: a live process that is not aimux's own holds the session (harness.LiveSessions, through Holders).
  • RegistryStatus: the harness's own registry status of that process ("busy", "idle", "" when it has none).
  • Background: aimux runs a turn of the session (the remote API's Broker).
  • Approval: that turn waits for a permission answer.
  • Waiting: a permission marker a hook wrote for the session.
  • Screen: the terminal screen shows the agent working, when read.
  • Fallback: a per-harness guess from the transcript tail, for a harness without a registry status.

The precedence rule, written once (Decide):

needs_you  a marker, a pending approval, or a held session whose registry
           status is "waiting"
working    an aimux turn, registry busy, or the screen shows working
           (else, for a held session nothing above describes, the
           fallback's needs_you or working)
idle       held, or an aimux run, and not working
gone       no process holds it and nothing runs

Place says where it lives: background while aimux runs it, terminal while a process holds it, none otherwise.

The package names no harness: harness-specific readers are supplied by the callers that build the Service.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Activity

type Activity string

Activity is what a session is doing now.

const (
	NeedsYou Activity = "needs_you" // a permission prompt or an approval waits for the owner
	Working  Activity = "working"
	Idle     Activity = "idle"
	Gone     Activity = "gone" // no process holds it and nothing runs
)

The activities, as the remote API sends them.

func (Activity) Label

func (a Activity) Label() string

Label is the activity as the TUI and the dashboard print it: "needs you", "working", "idle"; "" for gone or unknown, which they leave unlabelled.

type ApprovalReader

type ApprovalReader interface {
	AwaitingApproval(id string) bool
}

ApprovalReader reports a pending permission request of aimux's own run.

type BusyReader

type BusyReader interface {
	Busy(id string) bool
}

BusyReader reports aimux's own running turns (the remote API's Broker).

type Facts

type Facts struct {
	Held           bool
	RegistryStatus string
	Background     bool
	Approval       bool
	Waiting        *Wait
	Screen         Screen
	Fallback       Activity
}

Facts are the inputs about one session.

type Place

type Place string

Place is where a session lives.

const (
	Terminal   Place = "terminal"   // a process outside aimux holds it
	Background Place = "background" // aimux's own (ACP) run
	None       Place = "none"
)

The places.

type Screen

type Screen int

Screen is what a read of the terminal screen says.

const (
	ScreenUnknown Screen = iota // not read
	ScreenIdle
	ScreenWorking
)

The screen readings.

type Service

type Service struct {
	// Holders is the sessions a live process that is not aimux's own holds,
	// one holder each (catalog.Open, harness.OpenSessions).
	Holders func() map[string]harness.Holder
	// Busy and Approvals are aimux's own runs; nil in processes that run
	// none (TUI, dashboard).
	Busy      BusyReader
	Approvals ApprovalReader
	// Markers is the live permission markers by session (waiting.Tracker).
	Markers func() map[string]Wait
	// Fallback is each harness's transcript guess, for sessions whose
	// harness has no registry status.
	Fallback func() map[string]Activity
}

Service answers Of and All from its inputs. Every input is optional (nil: the source says nothing) and must be cheap: memory or cached reads, since the TUI asks on every refresh and the remote API on every list.

func (*Service) All

func (s *Service) All() map[string]State

All is Read().All().

func (*Service) Of

func (s *Service) Of(id string) State

Of is id's State now; sessions no input knows are gone.

func (*Service) Read

func (s *Service) Read() Snapshot

Read takes a Snapshot: each map input is read once.

type Snapshot

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

Snapshot is one read of the map-shaped inputs; Of on it asks only the per-session readers (Busy, Approvals), which are memory lookups.

func (Snapshot) All

func (n Snapshot) All() map[string]State

All is the State of every session a map input knows (held, marked or guessed). A session only aimux's run knows is answered by Of, not listed: the Busy reader cannot be enumerated.

func (Snapshot) Facts

func (n Snapshot) Facts(id string) Facts

Facts is everything the inputs say about id.

func (Snapshot) Holders

func (n Snapshot) Holders() map[string]harness.Holder

Holders is this snapshot's holders read, in a map of the caller's own: the remote list derives state and working from it, so they cannot disagree with the activity.

func (Snapshot) Of

func (n Snapshot) Of(id string) State

Of is id's State in this snapshot (Decide over Facts).

type State

type State struct {
	Activity Activity
	Place    Place
	Facts
}

State is the answer for one session, with the facts it came from.

func Decide

func Decide(f Facts) State

Decide applies the precedence rule (package doc) to f.

type Wait

type Wait struct {
	Kind    string    `json:"kind"`
	Message string    `json:"message"`
	Since   time.Time `json:"since"`
}

Wait is what a session waits for, from a marker: the remote API's `waiting` object.

Jump to

Keyboard shortcuts

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