tui

package
v0.8.19 Latest Latest
Warning

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

Go to latest
Published: Oct 9, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package tui implements Relayer's Bubble Tea user interface.

The package deliberately knows nothing about PTYs or process management. A Backend supplies the small set of operations needed by the UI, which keeps rendering and interaction tests deterministic.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AgentViewportSize

func AgentViewportSize(width, height, agentCount, agentIndex int) (columns, rows int)

AgentViewportSize returns the viewport (and therefore PTY) size of an agent, including agents that are currently on a hidden page.

Types

type AttachableBackend

type AttachableBackend interface {
	Name() string
	AttachCommand(ctx context.Context, id string) (*exec.Cmd, error)
	Resync(ctx context.Context, id string, columns, rows int) error
}

AttachableBackend is an optional capability implemented by backends, such as tmux, that can temporarily hand a live session to the user's terminal. Resync must restore the pane size and reconcile captured output, lifecycle state and prompts before returning.

type AutomaticDecisionBackend

type AutomaticDecisionBackend interface {
	SendAutomaticDecision(id string, event adapters.Event, decision adapters.Decision) error
}

AutomaticDecisionBackend encodes a semantic allow/deny decision with the adapter that produced event and delivers it through the backend's exact occurrence-ID CAS path. Implementations must never invent terminal bytes.

type Backend

type Backend interface {
	Context() context.Context
	Output(id string) (string, error)
	SendInput(id string, value string) error
	Resize(id string, columns, rows int) error
	BeginShutdown()
}

Backend is the process/session boundary consumed by the TUI.

type Cell

type Cell struct {
	AgentIndex     int
	Outer          Rect
	ViewportWidth  int
	ViewportHeight int
}

Cell is the complete layout contract for one visible agent. Its viewport dimensions are the dimensions that must also be applied to the agent PTY.

type ContextResizeBackend

type ContextResizeBackend interface {
	ResizeContext(ctx context.Context, id string, columns, rows int) error
}

ContextResizeBackend is an optional non-blocking resize capability used by the production adapter. The TUI executes these calls outside Update and can cancel a superseded batch. Lightweight test and legacy PTY backends keep the synchronous Resize fallback above.

type DecisionBackend

type DecisionBackend interface {
	SendDecision(id string, event adapters.Event, manualInput string) error
}

DecisionBackend encodes and delivers a manual decision through the adapter that produced the exact event occurrence.

type EventSnapshotBackend

type EventSnapshotBackend interface {
	PendingEvent(context.Context, string) (*adapters.Event, error)
}

PromptSnapshotBackend lets the attach callback make backend state authoritative over events that may have been queued while Bubble Tea was suspended by tea.ExecProcess. Implementations must return cached state and must not run an external command from Bubble Tea's Update call.

type FocusKind

type FocusKind uint8

FocusKind makes the keyboard target explicit instead of overloading a pane index with a supervisor sentinel.

const (
	FocusAgent FocusKind = iota + 1
	FocusSupervisor
)

type FocusTarget

type FocusTarget struct {
	Kind    FocusKind
	AgentID string
}

FocusTarget identifies either an agent by its stable ID or the supervisor. AgentID is empty when Kind is FocusSupervisor.

type Geometry

type Geometry struct {
	Width                    int
	Height                   int
	AgentArea                Rect
	Supervisor               Rect
	Cells                    []Cell
	Page                     int
	PageCount                int
	SupervisorViewportWidth  int
	SupervisorViewportHeight int
	InputWidth               int
}

Geometry is the single source of truth for rendering, mouse hit testing and PTY sizing. Page is zero based; PageCount is always at least one.

func CalculateLayout

func CalculateLayout(width, height, agentCount, page int) Geometry

CalculateLayout divides the terminal into a 75% agent area and a 25% supervisor area. Each page displays at most four agents: one full-width cell, two columns, a 2+1 layout, or a 2x2 grid.

type LineInputBackend

type LineInputBackend interface {
	SendLine(id, value string) error
}

LineInputBackend sends one deliberate operator line only while the core can prove that the target session has no pending semantic event. It is separate from DecisionBackend: a line must never acknowledge or answer a prompt, and callers must not fall back to Backend.SendInput when this capability is absent.

type Model

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

Model is Relayer's Bubble Tea model. It uses a pointer receiver deliberately: viewport and pane slices must retain one identity as the number of agents and the visible page change.

func NewModel

func NewModel(
	backend Backend,
	events <-chan session.Event,
	panes []Pane,
	initialWidth int,
	initialHeight int,
	startupLogs []string,
) (*Model, error)

NewModel builds a ready-to-run Bubble Tea model around one to eight existing sessions. Pane identity is copied and validated before any resize occurs.

func NewModelWithPolicy

func NewModelWithPolicy(
	backend Backend,
	events <-chan session.Event,
	panes []Pane,
	initialWidth int,
	initialHeight int,
	startupLogs []string,
	evaluator PolicyEvaluator,
) (*Model, error)

NewModelWithPolicy adds pure policy evaluation while keeping NewModel's historical, safe ask-by-default behavior for existing callers.

func NewModelWithPolicyAndAudit

func NewModelWithPolicyAndAudit(
	backend Backend,
	events <-chan session.Event,
	panes []Pane,
	initialWidth int,
	initialHeight int,
	startupLogs []string,
	evaluator PolicyEvaluator,
	auditor *audit.Recorder,
) (*Model, error)

NewModelWithPolicyAndAudit enables the synchronous local audit trail. The caller retains ownership of auditor and must close it after Bubble Tea and the backends have completed their lifecycle.

func (*Model) Init

func (m *Model) Init() tea.Cmd

func (*Model) MetricsActive added in v0.3.0

func (m *Model) MetricsActive() bool

MetricsActive reports whether the metrics overlay is currently shown.

func (*Model) SetNotifier

func (m *Model) SetNotifier(n notify.Notifier)

SetNotifier configures the notification dispatcher for the TUI model.

func (*Model) ToggleMetrics added in v0.3.0

func (m *Model) ToggleMetrics()

ToggleMetrics toggles visibility of the live session metrics overlay.

func (*Model) Update

func (m *Model) Update(message tea.Msg) (tea.Model, tea.Cmd)

func (*Model) View

func (m *Model) View() string

type Pane

type Pane struct {
	ID      string
	Name    string
	Command string
	Backend string
	Adapter string
	Shell   bool
}

Pane describes one agent already started by the caller.

type PolicyEvaluator

type PolicyEvaluator interface {
	Evaluate(adapters.Event) policy.Evaluation
	Config() policy.Config
}

PolicyEvaluator is deliberately pure. Bubble Tea owns orchestration state while policy.Engine decides whether an actionable occurrence is automatic.

type Rect

type Rect struct {
	X      int
	Y      int
	Width  int
	Height int
}

Rect is an outer terminal rectangle. Coordinates are zero based and Width and Height include the Lip Gloss border of the panel.

func (Rect) Contains

func (r Rect) Contains(x, y int) bool

Contains reports whether a terminal coordinate is inside the rectangle.

type SessionExitObserver added in v0.8.6

type SessionExitObserver interface {
	MarkSessionExited(id string)
}

SessionExitObserver is the optional capability of being told that an agent exited on its own. The TUI calls it off the Update loop.

type SessionLifecycleBackend added in v0.4.0

type SessionLifecycleBackend interface {
	StopSession(id string) error
	StartSession(id string) error
	RestartSession(id string) error
}

SessionLifecycleBackend is the optional hot per-agent lifecycle capability. Implementations audit every transition with the operator as its actor and never start a replacement process while a previous stop stays unconfirmed. The TUI invokes these outside Update through a Bubble Tea command so the interface never blocks on process teardown.

Jump to

Keyboard shortcuts

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