Documentation
¶
Overview ¶
Package app implements Harbor's deterministic terminal shell.
Index ¶
- Constants
- Variables
- func Run(ctx context.Context, input io.Reader, output io.Writer, model tea.Model) error
- func RunTerminal(ctx context.Context, model tea.Model) error
- type ActionIntent
- type ActionSpec
- type BackdropMsg
- type Command
- type CommandID
- type CommandMsg
- type CommandView
- type ComposerState
- type Confirmation
- type Context
- type FocusStack
- type Layer
- type Model
- func NewModel(width, height int, theme ui.Theme, reducedMotion bool, p projection.Projection) Model
- func NewModelFromEnvironment(width, height int, environment ui.Environment, reducedMotion bool, ...) Model
- func NewOperationalModel(width, height int, theme ui.Theme, reducedMotion bool, p projection.Projection) Model
- func (m Model) Frame() string
- func (m Model) Init() tea.Cmd
- func (m Model) Layout() ui.Layout
- func (m Model) OpenPalette() Model
- func (m Model) Update(message tea.Msg) (tea.Model, tea.Cmd)
- func (m Model) View() tea.View
- func (m Model) WithModal(modal SelectModel) Model
- func (m Model) WithState(state State) Model
- func (m Model) WithTerminalBackground(dark bool) Model
- type ReconcileMode
- type Registry
- func (r Registry) Command(id CommandID, ctx Context) (CommandView, bool)
- func (r Registry) Dispatch(key string, ctx Context) (CommandView, bool)
- func (r Registry) DispatchSequence(keys []string, ctx Context) (CommandView, bool)
- func (r Registry) Footer(ctx Context) []string
- func (r Registry) Help(ctx Context) []string
- func (r Registry) Palette(ctx Context) []CommandView
- func (r Registry) Prefix(strokes []string, ctx Context) (CommandView, bool, bool)
- func (r Registry) Resolve(ctx Context) []CommandView
- func (r Registry) WhichKey(leader string, ctx Context) []CommandView
- type RuntimeModel
- type RuntimeOptions
- type SelectItem
- type SelectModel
- func (m SelectModel) BackdropClose(textSelectionActive bool) bool
- func (m SelectModel) IsInput() bool
- func (m SelectModel) Move(delta int) SelectModel
- func (m SelectModel) PageBy(delta int) SelectModel
- func (m SelectModel) SetCategory(category string) SelectModel
- func (m SelectModel) SetQuery(query string) SelectModel
- func (m SelectModel) Visible() []SelectItem
- type StartupCompleteMsg
- type State
Constants ¶
const ( StandardSpinnerInterval = 80 * time.Millisecond ActiveSpinnerInterval = 40 * time.Millisecond SequenceTimeout = 2 * time.Second StartupDelay = 500 * time.Millisecond StartupMinimum = 3 * time.Second )
const InterruptTimeout = 1500 * time.Millisecond
InterruptTimeout is how long the first esc keeps the run interrupt armed.
Variables ¶
var LayerOrder = [...]Layer{LayerBase, LayerSidebar, LayerAutocomplete, LayerToast, LayerModal, LayerStartup}
Functions ¶
func RunTerminal ¶
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 CommandMsg ¶
type CommandMsg struct{ ID CommandID }
CommandMsg asks the operational host to execute one registry command.
type CommandView ¶
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 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) OpenPalette ¶
OpenPalette opens the registry-backed modal.
func (Model) WithModal ¶
func (m Model) WithModal(modal SelectModel) Model
func (Model) WithTerminalBackground ¶
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 ¶
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) Palette ¶
func (r Registry) Palette(ctx Context) []CommandView
Palette returns suggested entries first, then stable categories and titles.
func (Registry) Prefix ¶
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.
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) 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 ¶
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.