Documentation
¶
Overview ¶
Package app is declared in page.go; this file adds the App root model.
Package app defines the core types for the PromptArena TUI hub shell: the Page interface that every screen implements, AppContext that carries shared runtime dependencies, and the navigation messages used to push/pop pages or signal quit and config-change events.
Index ¶
- func DefaultMenu(ctx *AppContext) []menuItem
- func DiscoverConfig(dir string) (path string, found bool)
- func ResultsDirFromConfig(configPath string) string
- func Run(ctx *AppContext, root Page) error
- func RunWithProgram(ctx *AppContext, root Page, newProgram func(tea.Model) Program) error
- type Activatable
- type App
- type AppContext
- type ChatPage
- type Closeable
- type Composer
- type ConfigChangedMsg
- type ConfigSwitchPage
- type ConversationViewPage
- type DeployPage
- type Home
- type InspectPage
- type LogsOverlay
- type Page
- type PopPageMsg
- type Program
- type PushPageMsg
- type QuitMsg
- type ResultsPage
- type RunPage
- func (p *RunPage) Activate(send func(tea.Msg)) tea.Cmd
- func (p *RunPage) Cancel()
- func (p *RunPage) Init() tea.Cmd
- func (p *RunPage) Model() *tui.Model
- func (p *RunPage) Results() (runIDs []string, finished bool, err error)
- func (p *RunPage) SetSize(w, h int)
- func (p *RunPage) Title() string
- func (p *RunPage) Update(msg tea.Msg) (Page, tea.Cmd)
- func (p *RunPage) View() string
- type Splash
- type ViewPage
- type VoiceOptions
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DefaultMenu ¶
func DefaultMenu(ctx *AppContext) []menuItem
DefaultMenu returns the canonical menu items for the Home page.
View is always enabled (it only needs a results directory). Run, Chat, and Inspect require a loaded config.
func DiscoverConfig ¶
DiscoverConfig resolves an arena config path from dir.
If dir is itself a regular file it is returned directly. If dir is a directory, DiscoverConfig looks for config.arena.yaml inside it. Returns (path, true) on success or ("", false) when no config can be found.
func ResultsDirFromConfig ¶
ResultsDirFromConfig returns the conventional results directory (out/) next to the given config file. Callers that build an AppContext directly (e.g. chat/config-inspect subcommands) use this so the path matches what LoadConfig would have set.
func Run ¶
func Run(ctx *AppContext, root Page) error
Run launches the PromptArena TUI hub with root as the bottom page on the navigation stack. The splash screen is shown first — it is pushed on top of root so that dismissing it (via any key or the auto-dismiss timer) reveals root. App.Init() calls the top page's Init (once only), so the splash timer fires automatically under the bubbletea runtime.
The stack is seeded as [root, splash] before tea.NewProgram is called, which means:
- a.Init() → splash.Init() (timer starts; root is NOT yet inited)
- splash dismiss → PopPageMsg → root becomes top → root.Init() fires once (via initAndActivate in pop()) together with root.Activate() if applicable
The once-only Init guarantee ensures deep-link pages like ChatPage load their agents/setup state when revealed by splash dismiss, not before. Esc/q at root (the only page remaining after splash dismiss) will quit.
func RunWithProgram ¶
RunWithProgram is the testable core of Run. It seeds the stack, builds the program via newProgram, installs the slog interceptor wired to the program's Send (so runtime logs are captured into the TUI on every alt-screen path instead of corrupting the screen), runs the program, then flushes buffered logs to stderr and restores the default logger.
Types ¶
type Activatable ¶
Activatable is implemented by pages that need to push async messages into the running bubbletea program. The App calls Activate(send) when the page becomes the active/top page: at root startup (in App.Init) and on push. send is *tea.Program.Send — a thread-safe delivery channel. The returned tea.Cmd is an optional startup command; it is batched with the page's Init cmd by the App.
type App ¶
type App struct {
// contains filtered or unexported fields
}
App is the root bubbletea model for the PromptArena TUI hub shell. It owns the page navigation stack and routes messages globally.
func New ¶
func New(ctx *AppContext, root Page) *App
New creates a new App with root as the initial (bottom) page on the stack. root must not be nil.
func (*App) Init ¶
Init implements tea.Model. It runs the top page's Init command (once only) and batches it with an optional Activate cmd if the page implements Activatable.
func (*App) SetSend ¶
SetSend stores the program's Send func so that Activatable pages can push messages back into the bubbletea event loop from goroutines. Call this after tea.NewProgram and before p.Run().
type AppContext ¶
type AppContext struct {
Config *arenaconfig.Config
ConfigPath string
ResultsDir string
// ConfigErr and ConfigErrPath record the most recent failed LoadConfig
// attempt: a config file was found at ConfigErrPath but did not load (e.g.
// schema validation failed). They let the hub distinguish "a config exists
// but is invalid" from "no config at all". Both are cleared on a successful
// load. A load failure leaves Config unchanged (nil at startup, or a
// previously-loaded config if the user switched to a bad one at runtime).
ConfigErr error
ConfigErrPath string
StateStore statestore.Store
Engine *engine.Engine
Version string
Voice *VoiceOptions // nil => text chat
// Verbose raises the hub's log interceptor to debug level and (with
// LogDir set) tees logs to <LogDir>/promptarena.log. LogDir is the
// directory for that file — usually the run's output dir.
Verbose bool
LogDir string
}
AppContext carries the shared runtime dependencies injected into every Page by the hub shell. Fields are set once at startup and then treated as read-only by pages.
func (*AppContext) ConfigInvalid ¶ added in v1.5.7
func (c *AppContext) ConfigInvalid() bool
ConfigInvalid reports whether a config file was found but failed to load (e.g. schema validation), and no valid config is currently loaded. This is distinct from "no config at all": the hub surfaces the load error instead of telling the user there is no config to pick.
func (*AppContext) EnsureEngine ¶
func (c *AppContext) EnsureEngine() (*engine.Engine, error)
EnsureEngine returns the cached engine from ctx, building it from ctx.Config if it has not been built yet. It also sets ctx.StateStore from the engine. Returns an error if no config has been loaded.
func (*AppContext) HasConfig ¶
func (c *AppContext) HasConfig() bool
HasConfig reports whether a config has been loaded into this context.
func (*AppContext) LoadConfig ¶
func (c *AppContext) LoadConfig(path string) error
LoadConfig loads the arena configuration from path, sets Config and ConfigPath on the context, and derives ResultsDir as the out/ directory next to the config file.
func (*AppContext) ProjectDir ¶ added in v1.5.7
func (c *AppContext) ProjectDir() string
ProjectDir returns the project root directory for deploy operations, derived from the loaded config file's directory. It returns "" when no config is loaded (or the config path has no meaningful parent directory), letting callers such as flow.Options fall back to the current working directory themselves.
type ChatPage ¶
type ChatPage struct {
// contains filtered or unexported fields
}
ChatPage is a hub Page that drives the interactive chat console. It owns the setup flow (agent / provider / variable selection) and the live chat panel driven from the state store after each turn.
Implements Page and Activatable.
func NewChatPage ¶
func NewChatPage(ctx *AppContext) *ChatPage
NewChatPage constructs a ChatPage bound to the given AppContext. Activate must be called before Init to wire the engine.
func (*ChatPage) Activate ¶
Activate implements Activatable. It is called by App before Init. It calls EnsureEngine so Init can proceed. The send handle is stored so startVoice can push messages into the bubbletea loop from goroutines.
func (*ChatPage) Close ¶
func (p *ChatPage) Close()
Close implements Closeable. It cancels any running voice driver so the mic and pipeline shut down cleanly when the user quits.
func (*ChatPage) Init ¶
Init implements Page. It resolves the first setup step, auto-selecting when there is only one agent or provider so simple configs drop straight into chat.
type Closeable ¶
type Closeable interface {
Close()
}
Closeable is an optional interface a Page may implement to run cleanup logic when the App exits (e.g. canceling a background voice driver). App calls Close on every page in the stack when it processes a tea.Quit or QuitMsg.
type Composer ¶
type Composer struct {
// contains filtered or unexported fields
}
Composer renders the input affordance for an interactive conversation: a bordered text box (text mode) or a mic indicator (speech mode). It owns the presentation only — the host owns the underlying text-input model and its key handling — so the same component serves typed chat and voice chat.
func NewSpeechComposer ¶
func NewSpeechComposer() *Composer
NewSpeechComposer returns a Composer that renders a mic indicator.
func NewTextComposer ¶
func NewTextComposer() *Composer
NewTextComposer returns a Composer that renders a bordered text input box.
func (*Composer) SetSpeech ¶
SetSpeech switches the composer between speech (true) and text (false) modes. Hosts call this so the affordance tracks their current voice state.
type ConfigChangedMsg ¶
type ConfigChangedMsg struct{ Path string }
ConfigChangedMsg is emitted when the user loads or changes the arena config file. Path is the absolute path to the newly loaded file.
type ConfigSwitchPage ¶
type ConfigSwitchPage struct {
// contains filtered or unexported fields
}
ConfigSwitchPage wraps the file browser to let the user pick an arena config at runtime. On a successful selection it calls ctx.LoadConfig then emits both ConfigChangedMsg and PopPageMsg. On error it stays open and surfaces the error in its View.
func NewConfigSwitchPage ¶
func NewConfigSwitchPage(ctx *AppContext, startDir string) *ConfigSwitchPage
NewConfigSwitchPage creates a ConfigSwitchPage rooted at startDir. startDir is the initial directory shown in the file browser; a sensible default (dir of the current config, or ".") is chosen by callers.
func (*ConfigSwitchPage) Init ¶
func (p *ConfigSwitchPage) Init() tea.Cmd
Init implements Page. Delegates to the underlying file browser.
func (*ConfigSwitchPage) SetSize ¶
func (p *ConfigSwitchPage) SetSize(w, h int)
SetSize implements Page. Stores dimensions for View; does NOT call SetDimensions on the browser here because Render() is called from View() where we apply dimensions immediately before rendering.
func (*ConfigSwitchPage) Update ¶
Update implements Page. It intercepts FileSelectedMsg from the browser and drives the load-config flow; all other messages are forwarded to the browser.
Filtering note: FileBrowserPage uses AllowedTypes (extension list) which does not support glob patterns like "*.arena.yaml". The browser is therefore left unrestricted; invalid selections (non-YAML, non-arena files) are rejected via the LoadConfig error path and surfaced in the view.
func (*ConfigSwitchPage) View ¶
func (p *ConfigSwitchPage) View() string
View implements Page. Shows the file browser, or an error banner when the last selection failed.
type ConversationViewPage ¶
type ConversationViewPage struct {
// contains filtered or unexported fields
}
ConversationViewPage wraps pages.ConversationPage for use inside the hub shell navigation stack. When live, it streams runtime events into the panel (new turns, audio meter) until the run completes; otherwise it shows a static snapshot loaded from the state store.
func NewConversationViewPage ¶
func NewConversationViewPage(runID, scenarioID, providerID string, result *statestore.RunResult) *ConversationViewPage
NewConversationViewPage creates a ConversationViewPage pre-loaded with the given (completed-run) snapshot. It does not stream live events.
func NewLiveConversationViewPage ¶
func NewLiveConversationViewPage( runID, scenarioID, providerID string, seed *statestore.RunResult, store conversationStore, ) *ConversationViewPage
NewLiveConversationViewPage creates a ConversationViewPage that streams the conversation live while focused. seed may be a partial snapshot (turns so far) or nil; runtime events then trigger the liveFeed to reconcile the panel against store (the authoritative transcript), so the live view stays in lock-step with what the completed view will show. store may be nil (no live reconcile, seed-only). The page reverts to static once the run completes.
func (*ConversationViewPage) Init ¶
func (p *ConversationViewPage) Init() tea.Cmd
Init implements Page.
func (*ConversationViewPage) SetSize ¶
func (p *ConversationViewPage) SetSize(w, h int)
SetSize implements Page.
func (*ConversationViewPage) Title ¶
func (p *ConversationViewPage) Title() string
Title implements Page.
func (*ConversationViewPage) Update ¶
Update implements Page. While live, runtime events are applied to the panel via the feed; run completion flips the page back to static. Other messages (scroll/focus keys) forward to the underlying conversation panel.
func (*ConversationViewPage) View ¶
func (p *ConversationViewPage) View() string
View implements Page. When the logs overlay is visible it replaces the conversation body; otherwise the conversation renders as usual.
type DeployPage ¶ added in v1.5.7
type DeployPage struct {
// contains filtered or unexported fields
}
DeployPage is the guided deploy wizard: preflight check, adapter login, plan, confirm, apply, and status, driven by the arena/deploy/flow package.
func (*DeployPage) Activate ¶ added in v1.5.7
func (p *DeployPage) Activate(send func(tea.Msg)) tea.Cmd
Activate implements Activatable. It stores the send handle and kicks off the background preflight probe.
func (*DeployPage) Close ¶ added in v1.5.7
func (p *DeployPage) Close()
Close implements Closeable. It cancels any in-flight flow.Login goroutine so that popping the page (e.g. pressing esc during deployStateLogin, which App's global esc handler pops before handleLoginKey ever sees the key) does not leave the login goroutine and its loopback OAuth callback server running against a page nothing is listening to anymore. It also cancels any in-flight planning goroutine and closes the flow.Session opened by startPlan — the session holds an adapter subprocess that MUST be released when the page is popped, however the wizard got here (plan failure, esc during planning/plan/confirm, or a later successful apply). It also cancels any in-flight startApply goroutine; that cancellation is best-effort since Apply is a single blocking call with no intermediate abandon checkpoint (unlike Open/Plan), so the adapter subprocess may still be mid-Apply when sess is closed just below — exactly the same race already accepted for an in-flight Plan call. It also cancels any in-flight startStatus goroutine, on the same best-effort basis as startApply.
func (*DeployPage) Init ¶ added in v1.5.7
func (p *DeployPage) Init() tea.Cmd
Init implements Page. No command runs here — Activate kicks off preflight once the page is pushed onto the navigation stack.
func (*DeployPage) SetSize ¶ added in v1.5.7
func (p *DeployPage) SetSize(w, h int)
SetSize implements Page.
func (*DeployPage) Title ¶ added in v1.5.7
func (p *DeployPage) Title() string
Title implements Page.
type Home ¶
type Home struct {
// contains filtered or unexported fields
}
Home is the top-level navigation page for the PromptArena TUI hub shell. It is generic over its menu items so that the concrete Run/View/Chat/Inspect entries can be injected by the top-level wiring (Task 8) without baking them in here.
func NewHome ¶
func NewHome(ctx *AppContext, items []menuItem) *Home
NewHome creates a Home page backed by ctx and populated with items. Items whose needsConfig field is true are greyed and non-selectable when ctx.HasConfig() returns false.
type InspectPage ¶
type InspectPage struct {
// contains filtered or unexported fields
}
InspectPage is a scrollable hub page that displays the configuration inspector output (the same content as `promptarena config-inspect`).
func NewInspectPage ¶
func NewInspectPage(ctx *AppContext) *InspectPage
NewInspectPage creates an InspectPage with default render options. If ctx is nil or has no config loaded, a placeholder message is shown instead. This is the entry point used by the Home menu.
func NewInspectPageWithOptions ¶
func NewInspectPageWithOptions(ctx *AppContext, opts inspect.RenderOptions) *InspectPage
NewInspectPageWithOptions creates an InspectPage with the given render options, allowing callers to thread --verbose/--section/--stats/--short flags through from the CLI. If ctx is nil or has no config loaded, a placeholder is shown.
func (*InspectPage) SetSize ¶
func (p *InspectPage) SetSize(w, h int)
SetSize implements Page. Initializes (or re-initializes) the viewport.
func (*InspectPage) View ¶
func (p *InspectPage) View() string
View implements Page. Renders the scrollable content above a consistent footer key-hint bar (shared with the other hub pages).
type LogsOverlay ¶
type LogsOverlay struct {
// contains filtered or unexported fields
}
LogsOverlay is a reusable, toggleable log view. Hosts (conversation drill-in, chat) feed it logging.Msg values; it buffers them (capped) and renders the shared LogsPanel when visible. It is the in-page counterpart to the run monitor's Logs pane, so runtime logs are inspectable everywhere a hub TUI owns the screen instead of corrupting it.
func NewLogsOverlay ¶
func NewLogsOverlay() *LogsOverlay
NewLogsOverlay creates an empty, hidden LogsOverlay.
func (*LogsOverlay) Append ¶
func (o *LogsOverlay) Append(m logging.Msg)
Append records a log line, trimming the oldest beyond the cap, and scrolls to the newest line.
func (*LogsOverlay) SetSize ¶
func (o *LogsOverlay) SetSize(w, h int)
SetSize stores the overlay dimensions and re-lays the panel.
func (*LogsOverlay) Update ¶
func (o *LogsOverlay) Update(msg tea.Msg) tea.Cmd
Update forwards scroll keys to the underlying viewport while visible.
func (*LogsOverlay) View ¶
func (o *LogsOverlay) View() string
View renders the logs when visible, empty otherwise.
func (*LogsOverlay) Visible ¶
func (o *LogsOverlay) Visible() bool
Visible reports whether the overlay is shown.
type Page ¶
type Page interface {
Init() tea.Cmd
Update(tea.Msg) (Page, tea.Cmd)
View() string
Title() string
SetSize(w, h int)
}
Page is the interface that every screen in the TUI hub must implement. It mirrors the bubbletea Model interface but returns (Page, tea.Cmd) from Update so that the shell can swap the active page in response to navigation messages.
func NewDeployPage ¶ added in v1.5.7
func NewDeployPage(ctx *AppContext) Page
NewDeployPage builds the deploy wizard page for ctx. It is the entry point used by the Home menu's Deploy item.
type PopPageMsg ¶
type PopPageMsg struct{}
PopPageMsg instructs the hub shell to pop the current page, returning to the previous one.
type Program ¶
Program is the slice of *tea.Program that Run depends on. It exists as a test seam so RunWithProgram can drive a fake program without a real terminal. A *tea.Program satisfies it.
type PushPageMsg ¶
type PushPageMsg struct{ Page Page }
PushPageMsg instructs the hub shell to push a new page onto the navigation stack, making it the active page.
type ResultsPage ¶
type ResultsPage struct {
// contains filtered or unexported fields
}
ResultsPage wraps MainPage to display the results loaded from a summary (index.json). The user can navigate the runs table and press Enter to dive into a ConversationViewPage.
func NewResultsPage ¶
func NewResultsPage(summary map[string]interface{}, resultsDir string) *ResultsPage
NewResultsPage creates a ResultsPage for the given summary and directory.
func (*ResultsPage) Init ¶
func (p *ResultsPage) Init() tea.Cmd
Init implements Page. Triggers async loading of all run results listed in the summary.
type RunPage ¶
type RunPage struct {
// contains filtered or unexported fields
}
RunPage drives the live run view inside the hub shell. It wraps the tui.Model (the 3-pane runs/logs/result view) and, on Activate, wires an event bus + adapter to stream runtime events into the model and kicks off engine.ExecuteRuns in a background goroutine. Drill-down into a run's conversation is handled at the App-stack level: when the model reports a selected run, RunPage pushes a ConversationViewPage loaded from the state store.
Implements Page and Activatable.
func NewRunPage ¶
func NewRunPage( ctx *AppContext, eng *engine.Engine, plan *engine.RunPlan, concurrency int, configFile string, totalRuns int, ) *RunPage
NewRunPage builds a RunPage for the given engine and run plan. The run command performs setupEngine / plan generation and hands the results in; RunParameters lives in package main and cannot be imported here, so callers pass the already-built engine, plan, concurrency, configFile and totalRuns.
func NewRunPageFromContext ¶
func NewRunPageFromContext(ctx *AppContext) (*RunPage, error)
NewRunPageFromContext is a convenience constructor for the Home menu factory. It calls EnsureEngine, generates a full (unfiltered) run plan, and returns a RunPage ready to be pushed onto the navigation stack. The default concurrency is 1 so the menu can always succeed without extra flags.
func (*RunPage) Activate ¶
Activate implements Activatable. It wires the event bus + adapter to deliver runtime events via send and starts ExecuteRuns in the background. The run results persist to the engine's state store as today. Returns the model's Init command.
func (*RunPage) Cancel ¶
func (p *RunPage) Cancel()
Cancel stops the background run. Safe to call after the hub exits so an early quit ('q' / Ctrl+C) does not leak the ExecuteRuns goroutine.
func (*RunPage) Results ¶
Results returns the run IDs produced by ExecuteRuns, whether the run finished, and any execution error. Safe for concurrent use; intended to be read by the run command after the hub exits.
func (*RunPage) SetSize ¶
SetSize implements Page. Forwards the terminal size to the model as a WindowSizeMsg (the model tracks its own width/height).
type Splash ¶
type Splash struct {
// contains filtered or unexported fields
}
Splash is the transient splash-screen Page shown at launch. It displays the locked PromptKit logo, a wordmark with the version, and a tagline. It dismisses on any key press or after splashDuration.
func NewSplash ¶
func NewSplash(ctx *AppContext) *Splash
NewSplash creates a Splash page backed by the given AppContext. The version string from ctx is rendered on the screen; pass ctx.Version = "vTEST" (or similar fixed string) in golden tests to keep output byte-stable.
type ViewPage ¶
type ViewPage struct {
// contains filtered or unexported fields
}
ViewPage wraps a file browser to let the user navigate past Arena result directories. Selecting a file triggers an async load; the result msg is then used to push either a ResultsPage (index.json) or ConversationViewPage.
func NewViewPage ¶
NewViewPage creates a ViewPage rooted at resultsDir.
type VoiceOptions ¶
type VoiceOptions struct {
STTProviderID string // --voice-stt ("" = ASM/native realtime mode)
OutputVoice string // --voice-output-voice
EchoGuard bool // --echo-guard
BargeIn bool // --barge-in (interrupt the agent mid-reply; opt-in)
TurnDetectionMode string // "asm" | "vad"; "" defaults to ASM
}
VoiceOptions carries the interactive-session parameters. A nil *VoiceOptions on AppContext means plain text chat; non-nil means a live mic/speaker session.
func DetectInteractiveSession ¶
func DetectInteractiveSession(cfg *arenaconfig.Config) *VoiceOptions
DetectInteractiveSession inspects a loaded config and, if it describes a realtime pipeline, returns VoiceOptions configured to honor its turn-detection mode. Two signals count: a scenario with an explicit Duplex block (honors its ASM/VAD mode), or a native-realtime provider (additional_config.realtime:true, e.g. OpenAI Realtime — ASM). It returns nil for plain text-chat configs, so `chat` lights up a live mic/speaker session automatically whenever the config calls for one — no --voice flag needed.