app

package
v1.17.1 Latest Latest
Warning

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

Go to latest
Published: Jul 21, 2026 License: Apache-2.0 Imports: 35 Imported by: 0

Documentation

Overview

Package app implements Harbor's deterministic terminal shell.

Index

Constants

View Source
const (
	StandardSpinnerInterval = 80 * time.Millisecond
	ActiveSpinnerInterval   = 40 * time.Millisecond
	SequenceTimeout         = 2 * time.Second
	StartupDelay            = 500 * time.Millisecond
	StartupMinimum          = 3 * time.Second
)
View Source
const InterruptTimeout = 1500 * time.Millisecond

InterruptTimeout is how long the first esc keeps the run interrupt armed.

Variables

Functions

func Run

func Run(ctx context.Context, input io.Reader, output io.Writer, model tea.Model) error

Run mounts one model and waits for Bubble Tea terminal cleanup on every path.

func RunTerminal

func RunTerminal(ctx context.Context, model tea.Model) error

RunTerminal mounts a model on the process terminal using Bubble Tea's default TTY discovery and raw-mode lifecycle. Alternate-scroll mode is enabled for the program's lifetime so mouse-wheel motion arrives as arrow keys on the alternate screen — scrolling works without ever capturing the mouse, which keeps the terminal's native text selection intact.

Types

type ActionIntent

type ActionIntent struct {
	ActionID, Title, RequiredAuthority string
	Identity                           types.IdentityScope
	Generation, RequestEpoch           uint64
	Method                             methods.Method
	RunID, PauseToken                  string
	ToolID, ArtifactID, SessionID      string
	Input                              string
	Confirmation                       Confirmation
	// contains filtered or unexported fields
}

ActionIntent is the immutable value displayed by confirmation and executed by the mutation executor. Payload is frozen JSON so later model updates cannot alter a target, PauseToken, input, or decision.

func (ActionIntent) Payload

func (i ActionIntent) Payload() map[string]any

type ActionSpec

type ActionSpec struct {
	ID, Title, Target, Scope, Outcome, DisabledReason string
	Method                                            methods.Method
	Capability                                        types.Capability
	Confirmation                                      Confirmation
	Reconcile                                         ReconcileMode
}

ActionSpec is the closed action matrix for every displayed mutation.

func ActionMatrix

func ActionMatrix() []ActionSpec

ActionMatrix returns a copied deterministic matrix. No UI action exists outside this inventory and no entry names a non-canonical method.

type BackdropMsg

type BackdropMsg struct{ TextSelectionActive bool }

BackdropMsg reports a backdrop release and whether terminal text selection is active.

type Command

type Command struct {
	ID                           CommandID
	Title, Description, Category string
	Bindings                     []string
	Suggested, Hidden            bool
	Enabled                      func(Context) (bool, string)
}

Command describes one dispatch, palette, which-key, footer, and help entry.

type CommandID

type CommandID string

CommandID is a stable command registry key.

type CommandMsg

type CommandMsg struct{ ID CommandID }

CommandMsg asks the operational host to execute one registry command.

type CommandView

type CommandView struct {
	Command        Command
	Enabled        bool
	DisabledReason string
}

CommandView is a resolved command with its disabled reason.

type ComposerState

type ComposerState string

ComposerState selects a composer posture.

const (
	ComposerIdle       ComposerState = "idle"
	ComposerFocused    ComposerState = "focused"
	ComposerDisabled   ComposerState = "disabled"
	ComposerRunning    ComposerState = "running"
	ComposerRetry      ComposerState = "retry · submit again"
	ComposerAttachment ComposerState = "attachment · report.pdf"
)

type Confirmation

type Confirmation string

Confirmation is the action's required operator confirmation level.

const (
	ConfirmNone        Confirmation = "none"
	ConfirmExplicit    Confirmation = "explicit"
	ConfirmDestructive Confirmation = "destructive"
)

type Context

type Context struct {
	ModalOpen, Connected, Erased, HasTranscript, HasAttachment, HasFollowUp bool
	TaskControl, SessionLifecycle, SessionScope                             bool
}

Context is the command activation context.

type FocusStack

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

FocusStack is one modal and focus restoration stack.

func NewFocusStack

func NewFocusStack(base string) FocusStack

NewFocusStack starts with one base focus target.

func (FocusStack) Focus

func (s FocusStack) Focus() string

Focus returns the top modal focus or base target.

func (FocusStack) Pop

func (s FocusStack) Pop() (FocusStack, string, bool)

Pop closes only the top modal and returns the restored focus.

func (FocusStack) Push

func (s FocusStack) Push(modal SelectModel) FocusStack

Push adds a modal and captures the active focus target.

func (FocusStack) ReplaceTop

func (s FocusStack) ReplaceTop(modal SelectModel) FocusStack

ReplaceTop applies an updated select value.

func (FocusStack) Top

func (s FocusStack) Top() (SelectModel, bool)

Top returns the top select model.

type Layer

type Layer uint8
const (
	LayerBase Layer = iota
	LayerSidebar
	LayerAutocomplete
	LayerToast
	LayerModal
	LayerStartup
)

type Model

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

Model is a value-updated Bubble Tea shell. All constructor inputs are cloned.

func NewModel

func NewModel(width, height int, theme ui.Theme, reducedMotion bool, p projection.Projection) Model

NewModel constructs the detached terminal foundation.

func NewModelFromEnvironment

func NewModelFromEnvironment(width, height int, environment ui.Environment, reducedMotion bool, p projection.Projection) Model

NewModelFromEnvironment compiles terminal capabilities before construction.

func NewOperationalModel

func NewOperationalModel(width, height int, theme ui.Theme, reducedMotion bool, p projection.Projection) Model

NewOperationalModel constructs a shell whose chrome is derived only from canonical conversation/session projection and local interaction state.

func (Model) Frame

func (m Model) Frame() string

func (Model) Init

func (m Model) Init() tea.Cmd

func (Model) Layout

func (m Model) Layout() ui.Layout

func (Model) OpenPalette

func (m Model) OpenPalette() Model

OpenPalette opens the registry-backed modal.

func (Model) Update

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

Update applies one deterministic model transition. Modal input always wins.

func (Model) View

func (m Model) View() tea.View

func (Model) WithModal

func (m Model) WithModal(modal SelectModel) Model

func (Model) WithState

func (m Model) WithState(state State) Model

func (Model) WithTerminalBackground

func (m Model) WithTerminalBackground(dark bool) Model

WithTerminalBackground re-compiles the palette for the terminal's real background, preserving the operator's explicit theme override.

type ReconcileMode

type ReconcileMode string

ReconcileMode describes what may update optimistically before canonical state.

const (
	ReconcileNone     ReconcileMode = "no optimistic mutation"
	ReconcileAccepted ReconcileMode = "show accepted pending canonical event"
)

type Registry

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

Registry is an immutable command catalog.

func DefaultRegistry

func DefaultRegistry() Registry

DefaultRegistry returns the shell's complete command source.

func NewRegistry

func NewRegistry(commands ...Command) (Registry, error)

NewRegistry validates and copies command definitions.

func (Registry) Command

func (r Registry) Command(id CommandID, ctx Context) (CommandView, bool)

Command resolves a command ID through the same enablement source.

func (Registry) Dispatch

func (r Registry) Dispatch(key string, ctx Context) (CommandView, bool)

Dispatch resolves one key through the same registry.

func (Registry) DispatchSequence

func (r Registry) DispatchSequence(keys []string, ctx Context) (CommandView, bool)

DispatchSequence resolves a complete key sequence through the registry.

func (Registry) Footer

func (r Registry) Footer(ctx Context) []string

Footer returns compact hints from suggested reachable commands.

func (Registry) Help

func (r Registry) Help(ctx Context) []string

Help returns every visible command, including actionable disabled reasons.

func (Registry) Palette

func (r Registry) Palette(ctx Context) []CommandView

Palette returns suggested entries first, then stable categories and titles.

func (Registry) Prefix

func (r Registry) Prefix(strokes []string, ctx Context) (CommandView, bool, bool)

Prefix reports whether strokes are an exact command, a pending prefix, or unmatched.

func (Registry) Resolve

func (r Registry) Resolve(ctx Context) []CommandView

Resolve returns all visible command presentations from one source.

func (Registry) WhichKey

func (r Registry) WhichKey(leader string, ctx Context) []CommandView

WhichKey returns reachable commands beginning with a leader stroke.

type RuntimeModel

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

RuntimeModel joins the terminal foundation to one Protocol-only conversation controller.

func NewRuntimeModel

func NewRuntimeModel(ctx context.Context, width, height int, theme ui.Theme, controller conversationController, updates conversation.UpdateSource, options RuntimeOptions) RuntimeModel

NewRuntimeModel constructs the operational one-active-session application.

func (RuntimeModel) Finalize

func (m RuntimeModel) Finalize() error

Finalize synchronously saves the last model returned by Bubble Tea on every exit path, including keys, signals, context cancellation, and host errors.

func (RuntimeModel) Init

func (m RuntimeModel) Init() tea.Cmd

func (RuntimeModel) Update

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

func (RuntimeModel) View

func (m RuntimeModel) View() tea.View

type RuntimeOptions

type RuntimeOptions struct {
	Compact, ReducedMotion bool
	// ThemeLocked marks the supplied theme as an explicit operator choice;
	// terminal background auto-detection must not override it.
	ThemeLocked             bool
	Fingerprint, ExportPath string
	// BaseURL is the attach target, shown on the session banner.
	BaseURL string
	State   conversation.InteractionState
	Store   interactionStore
}

RuntimeOptions supplies local-only interaction state and output paths.

type SelectItem

type SelectItem struct {
	ID, Category, Title, Description string
	Current                          bool
	Actions                          []CommandID
}

SelectItem is one reusable modal/select row.

type SelectModel

type SelectModel struct {
	Title, Query, Category  string
	Items                   []SelectItem
	Current, Page, PageSize int
	ContextActions          []CommandID
	CloseOnBackdrop         bool
	RestoreFocus            string
	Label, Placeholder      string
	ErrorText               string
	Masked                  bool
	Validate                func(string) error
}

SelectModel stores search, category, current row, paging, context, backdrop, and focus restoration for every select-shaped dialog. A dialog with a non-empty Label is a free-text INPUT dialog instead of a pick list: Query holds the typed value, the caption names what the value is (never "Search:"), Masked hides secret echo, and Validate gates enter with an inline error.

func NewInput

func NewInput(title, label, placeholder string, masked bool, validate func(string) error, restoreFocus string) SelectModel

NewInput creates a free-text input dialog. The label names what the typed value IS ("New title"), the placeholder shows its expected shape, masked replaces the echo with dots for secrets, and validate (optional) runs on enter — a failure renders inline in the dialog instead of committing.

func NewSelect

func NewSelect(title string, items []SelectItem, restoreFocus string) SelectModel

NewSelect creates a copied, focus-restoring select model.

func (SelectModel) BackdropClose

func (m SelectModel) BackdropClose(textSelectionActive bool) bool

BackdropClose reports whether a backdrop release should close this modal. Active text selection keeps it open so terminal-native selection is safe.

func (SelectModel) IsInput

func (m SelectModel) IsInput() bool

IsInput reports whether this dialog captures free text rather than filtering a pick list.

func (SelectModel) Move

func (m SelectModel) Move(delta int) SelectModel

Move advances selection with wraparound.

func (SelectModel) PageBy

func (m SelectModel) PageBy(delta int) SelectModel

PageBy changes page without allowing a negative page.

func (SelectModel) SetCategory

func (m SelectModel) SetCategory(category string) SelectModel

SetCategory resets paging and selection for a category.

func (SelectModel) SetQuery

func (m SelectModel) SetQuery(query string) SelectModel

SetQuery resets paging and selection for a new filter. Editing also clears any inline validation error — the operator is already correcting it.

func (SelectModel) Visible

func (m SelectModel) Visible() []SelectItem

Visible returns search/category-filtered rows for the current page.

type StartupCompleteMsg

type StartupCompleteMsg struct{}

StartupCompleteMsg explicitly completes startup work.

type State

type State struct {
	Route                                        string
	Connection                                   string
	Composer                                     ComposerState
	ComposerText                                 string
	ComposerCursor, SelectionStart, SelectionEnd int
	AutocompleteRows                             []string
	AutocompleteIndex                            int
	AttachmentReady, HasFollowUp                 bool
	// HasTranscript marks that the full conversation projection has blocks even
	// when the shell's windowed copy is empty (the host filters and windows what
	// the shell renders, but transcript commands operate on the whole thing).
	HasTranscript                                                                      bool
	SelectedBlockID                                                                    string
	Negotiated, TaskControl, SessionLifecycle, SessionScope                            bool
	SidebarOpen, AutocompleteOpen, ToastOpen, Startup, Active, CursorHidden            bool
	InterruptArmed                                                                     bool
	Scrolled, ReplayGap, Reconciliation, Dropped, Overflow, Truncated, CountersPartial bool
	AggregateTruncated, AggregatesPartial, AnalyticsBounded                            bool
	Closed, Failed, Erased, Intervention, Unknown, Incomplete, Pasted, Focused         bool
	Toast                                                                              string
	DetailRows                                                                         []string
	Health                                                                             string
	// TurnStatus is the canonical per-turn anchor (model · Runtime-reported
	// duration) shown under a finished answer. Empty when there is nothing
	// honest to report.
	TurnStatus string
	// TurnFailed marks that the newest FOREGROUND turn reached a terminal
	// failure. The status strip renders an explicit failure line instead of
	// letting the composer quietly return to idle; the line clears when a
	// fresh turn is submitted (the newest foreground turn is then in-flight,
	// not failed). TurnFailedCode is the bounded Runtime error code — never
	// the raw error message, which stays on the diagnostics route.
	TurnFailed     bool
	TurnFailedCode string
	// Model is the Runtime's reported LLM model. Empty when the Runtime has not
	// advertised one — never guessed.
	Model string
	// Version / DisplayName / BaseURL feed the session banner. Version and
	// DisplayName come from the Runtime's advertised RuntimeInfo after the
	// post-attach inspect; BaseURL is the attach target. Empty until reported.
	Version, DisplayName, BaseURL string
}

State selects shell view state.

Jump to

Keyboard shortcuts

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